Updated to reflect the current state of ffserver (as I understand it).
[libav.git] / doc / ffserver-doc.html
CommitLineData
c70a2119
FB
1<HTML>
2<HEAD>
ae98a915
PG
3<!-- This HTML file has been created by texi2html 1.51
4 from ffserver-doc.texi on 19 November 2002 -->
bdd3c092 5
c70a2119
FB
6<TITLE>FFserver Documentation</TITLE>
7</HEAD>
8<BODY>
9<H1>FFserver Documentation</H1>
10<P>
11<P><HR><P>
12<H1>Table of Contents</H1>
13<UL>
ae98a915
PG
14<LI><A NAME="TOC1" HREF="ffserver-doc.html#SEC1">1 Introduction</A>
15<LI><A NAME="TOC2" HREF="ffserver-doc.html#SEC2">2 QuickStart</A>
c70a2119 16<UL>
ae98a915
PG
17<LI><A NAME="TOC3" HREF="ffserver-doc.html#SEC3">2.1 What can this do?</A>
18<LI><A NAME="TOC4" HREF="ffserver-doc.html#SEC4">2.2 What do I need?</A>
19<LI><A NAME="TOC5" HREF="ffserver-doc.html#SEC5">2.3 How do I make it work?</A>
20<LI><A NAME="TOC6" HREF="ffserver-doc.html#SEC6">2.4 What happens next?</A>
21<LI><A NAME="TOC7" HREF="ffserver-doc.html#SEC7">2.5 Troubleshooting</A>
c70a2119 22<UL>
ae98a915
PG
23<LI><A NAME="TOC8" HREF="ffserver-doc.html#SEC8">2.5.1 I don't hear any audio, but video is fine</A>
24<LI><A NAME="TOC9" HREF="ffserver-doc.html#SEC9">2.5.2 The audio and video loose sync after a while.</A>
25<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>
26<LI><A NAME="TOC11" HREF="ffserver-doc.html#SEC11">2.5.4 WMP 6.4 behaves differently to WMP 7.</A>
c70a2119 27</UL>
ae98a915
PG
28<LI><A NAME="TOC12" HREF="ffserver-doc.html#SEC12">2.6 What else can it do?</A>
29<LI><A NAME="TOC13" HREF="ffserver-doc.html#SEC13">2.7 Tips</A>
30<LI><A NAME="TOC14" HREF="ffserver-doc.html#SEC14">2.8 Why does the ?buffer / Preroll stop working after a time?</A>
31<LI><A NAME="TOC15" HREF="ffserver-doc.html#SEC15">2.9 Does the <CODE>?date=</CODE> stuff work.</A>
c70a2119
FB
32</UL>
33</UL>
34<P><HR><P>
bdd3c092 35
c70a2119
FB
36<P>
37FFserver Documentation
ae98a915 38<P>
bdd3c092 39
ae98a915 40</P>
bdd3c092 41
bdd3c092 42
bdd3c092 43
ae98a915 44<H1><A NAME="SEC1" HREF="ffserver-doc.html#TOC1">1 Introduction</A></H1>
c70a2119
FB
45
46<P>
47FFserver is a streaming server for both audio and video. It supports
48several live feeds, streaming from files and time shifting on live feeds
49(you can seek to positions in the past on each live feed, provided you
50specify a big enough feed storage in ffserver.conf).
51
ae98a915 52</P>
c70a2119
FB
53<P>
54This documentation covers only the streaming aspects of ffserver /
55ffmpeg. All questions about parameters for ffmpeg, codec questions,
56etc. are not covered here. Read <TT>`ffmpeg-doc.[texi|html]'</TT> for more
57information.
58
ae98a915 59</P>
c70a2119
FB
60
61
ae98a915 62<H1><A NAME="SEC2" HREF="ffserver-doc.html#TOC2">2 QuickStart</A></H1>
c70a2119
FB
63
64<P>
65[Contributed by Philip Gladstone, philip-ffserver at gladstonefamily dot net]
66
ae98a915 67</P>
c70a2119
FB
68
69
ae98a915 70<H2><A NAME="SEC3" HREF="ffserver-doc.html#TOC3">2.1 What can this do?</A></H2>
c70a2119
FB
71
72<P>
bdd3c092
PG
73When properly configured and running, you can capture video and audio in real
74time from a suitable capture card, and stream it out over the Internet to
75either Windows Media Player or RealAudio player (with some restrictions).
76
ae98a915 77</P>
c70a2119 78<P>
bdd3c092
PG
79It can also stream from files, though that is currently broken. Very often, a
80web server can be used to serve up the files just as well.
81
ae98a915
PG
82</P>
83<P>
84It can stream prerecorded video from .ffm files, though it is somewhat tricky
85to make it work correctly.
bdd3c092 86
ae98a915 87</P>
c70a2119
FB
88
89
ae98a915 90<H2><A NAME="SEC4" HREF="ffserver-doc.html#TOC4">2.2 What do I need?</A></H2>
c70a2119
FB
91
92<P>
bdd3c092
PG
93I use Linux on a 900MHz Duron with a cheapo Bt848 based TV capture card. I'm
94using stock linux 2.4.17 with the stock drivers. [Actually that isn't true,
95I needed some special drivers from my motherboard based sound card.]
96
ae98a915 97</P>
c70a2119 98<P>
bdd3c092
PG
99I understand that FreeBSD systems work just fine as well.
100
ae98a915 101</P>
bdd3c092 102
c70a2119 103
ae98a915 104<H2><A NAME="SEC5" HREF="ffserver-doc.html#TOC5">2.3 How do I make it work?</A></H2>
c70a2119
FB
105
106<P>
bdd3c092
PG
107First, build the kit. It *really* helps to have installed LAME first. Then when
108you run the ffserver ./configure, make sure that you have the --enable-mp3lame
109flag turned on.
110
ae98a915 111</P>
c70a2119 112<P>
bdd3c092
PG
113LAME is important as it allows streaming of audio to Windows Media Player. Don't
114ask why the other audio types do not work.
115
ae98a915 116</P>
c70a2119 117<P>
ae98a915
PG
118As a simple test, just run the following two command lines (assuming that you
119have a V4L video capture card):
c70a2119 120
ae98a915 121</P>
c70a2119
FB
122
123<PRE>
124./ffserver -f doc/ffserver.conf &#38;
bdd3c092 125./ffmpeg http://localhost:8090/feed1.ffm
c70a2119 126</PRE>
bdd3c092 127
c70a2119 128<P>
bdd3c092
PG
129At this point you should be able to go to your windows machine and fire up
130Windows Media Player (WMP). Go to Open URL and enter
131
ae98a915 132</P>
c70a2119
FB
133
134<PRE>
135 http://&#60;linuxbox&#62;:8090/test.asf
136</PRE>
137
138<P>
bdd3c092
PG
139You should see (after a short delay) video and hear audio.
140
ae98a915 141</P>
c70a2119 142<P>
96c7b535 143WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
ae98a915 144transfer the entire file before starting to play. The same is true of avi files.
bdd3c092 145
ae98a915 146</P>
c70a2119
FB
147
148
ae98a915 149<H2><A NAME="SEC6" HREF="ffserver-doc.html#TOC6">2.4 What happens next?</A></H2>
c70a2119
FB
150
151<P>
bdd3c092
PG
152You should edit the ffserver.conf file to suit your needs (in terms of
153frame rates etc). Then install ffserver and ffmpeg, write a script to start
154them up, and off you go.
155
ae98a915 156</P>
bdd3c092 157
bdd3c092 158
ae98a915 159<H2><A NAME="SEC7" HREF="ffserver-doc.html#TOC7">2.5 Troubleshooting</A></H2>
c70a2119 160
c70a2119
FB
161
162
ae98a915 163<H3><A NAME="SEC8" HREF="ffserver-doc.html#TOC8">2.5.1 I don't hear any audio, but video is fine</A></H3>
c70a2119
FB
164
165<P>
bdd3c092
PG
166Maybe you didn't install LAME, or get your ./configure statement right. Check
167the ffmpeg output to see if a line referring to mp3 is present. If not, then
168your configuration was incorrect. If it is, then maybe your wiring is not
169setup correctly. Maybe the sound card is not getting data from the right
170input source. Maybe you have a really awful audio interface (like I do)
171that only captures in stereo and also requires that one channel be flipped.
172If you are one of these people, then export 'AUDIO_FLIP_LEFT=1' before
173starting ffmpeg.
174
ae98a915 175</P>
bdd3c092 176
c70a2119 177
ae98a915 178<H3><A NAME="SEC9" HREF="ffserver-doc.html#TOC9">2.5.2 The audio and video loose sync after a while.</A></H3>
c70a2119
FB
179
180<P>
bdd3c092
PG
181Yes, they do.
182
ae98a915 183</P>
bdd3c092 184
c70a2119 185
ae98a915 186<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>
c70a2119
FB
187
188<P>
bdd3c092
PG
189Yes, it does. Who knows why?
190
ae98a915 191</P>
9cfe269e 192
c70a2119 193
ae98a915 194<H3><A NAME="SEC11" HREF="ffserver-doc.html#TOC11">2.5.4 WMP 6.4 behaves differently to WMP 7.</A></H3>
c70a2119
FB
195
196<P>
9cfe269e
PG
197Yes, it does. Any thoughts on this would be gratefully received. These
198differences extend to embedding WMP into a web page. [There are two
199different object ids that you can use, one of them -- the old one -- cannot
200play very well, and the new one works well (both on the same system). However,
201I suspect that the new one is not available unless you have installed WMP 7].
202
ae98a915 203</P>
bdd3c092 204
c70a2119 205
ae98a915 206<H2><A NAME="SEC12" HREF="ffserver-doc.html#TOC12">2.6 What else can it do?</A></H2>
c70a2119
FB
207
208<P>
ae98a915
PG
209You can replay video from .ffm files that was recorded earlier.
210However, there are a number of caveats which include the fact that the
211ffserver parameters must match the original parameters used to record the
212file. If not, then ffserver deletes the file before recording into it. (Now I write
213this, this seems broken).
c70a2119 214
ae98a915 215</P>
c70a2119 216<P>
bdd3c092
PG
217You can fiddle with many of the codec choices and encoding parameters, and
218there are a bunch more parameters that you cannot control. Post a message
219to the mailing list if there are some 'must have' parameters. Look in the
220ffserver.conf for a list of the currently available controls.
221
ae98a915 222</P>
c70a2119 223<P>
9cfe269e
PG
224It will automatically generate the .ASX or .RAM files that are often used
225in browsers. These files are actually redirections to the underlying .ASF
226or .RM file. The reason for this is that the browser often fetches the
227entire file before starting up the external viewer. The redirection files
228are very small and can be transferred quickly. [The stream itself is
229often 'infinite' and thus the browser tries to download it and never
230finishes.]
231
ae98a915 232</P>
bdd3c092 233
c70a2119 234
ae98a915 235<H2><A NAME="SEC13" HREF="ffserver-doc.html#TOC13">2.7 Tips</A></H2>
c70a2119
FB
236
237<P>
bdd3c092
PG
238* When you connect to a live stream, most players (WMP, RA etc) want to
239buffer a certain number of seconds of material so that they can display the
240signal continuously. However, ffserver (by default) starts sending data
241in real time. This means that there is a pause of a few seconds while the
242buffering is being done by the player. The good news is that this can be
243cured by adding a '?buffer=5' to the end of the URL. This says that the
244stream should start 5 seconds in the past -- and so the first 5 seconds
245of the stream is sent as fast as the network will allow. It will then
246slow down to real time. This noticeably improves the startup experience.
9cfe269e 247
ae98a915 248</P>
c70a2119 249<P>
9cfe269e
PG
250You can also add a 'Preroll 15' statement into the ffserver.conf that will
251add the 15 second prebuffering on all requests that do not otherwise
252specify a time. In addition, ffserver will skip frames until a key_frame
253is found. This further reduces the startup delay by not transferring data
254that will be discarded.
255
ae98a915 256</P>
c70a2119 257<P>
9cfe269e
PG
258* You may want to adjust the MaxBandwidth in the ffserver.conf to limit
259the amount of bandwidth consumed by live streams.
ce838977 260
ae98a915 261</P>
ce838977 262
c70a2119 263
ae98a915 264<H2><A NAME="SEC14" HREF="ffserver-doc.html#TOC14">2.8 Why does the ?buffer / Preroll stop working after a time?</A></H2>
c70a2119
FB
265
266<P>
ce838977
PG
267It turns out that (on my machine at least) the number of frames successfully
268grabbed is marginally less than the number that ought to be grabbed. This
269means that the timestamp in the encoded data stream gets behind real time.
270This means that if you say 'preroll 10', then when the stream gets 10
271or more seconds behind, there is no preroll left.
272
ae98a915 273</P>
c70a2119 274<P>
ae98a915 275Fixing this requires a change in the internals in how timestamps are
ce838977
PG
276handled.
277
ae98a915 278</P>
ce838977 279
c70a2119 280
ae98a915 281<H2><A NAME="SEC15" HREF="ffserver-doc.html#TOC15">2.9 Does the <CODE>?date=</CODE> stuff work.</A></H2>
c70a2119
FB
282
283<P>
ce838977 284Yes (subject to the caution above). Also note that whenever you start
ae98a915
PG
285ffserver, it deletes the ffm file (if any parameters hacve changed), thus wiping out what you had recorded
286before.
c70a2119 287
ae98a915 288</P>
c70a2119
FB
289<P>
290The format of the <CODE>?date=xxxxxx</CODE> is fairly flexible. You should use one
ce838977
PG
291of the following formats (the 'T' is literal):
292
ae98a915 293</P>
c70a2119
FB
294
295<PRE>
ce838977
PG
296* YYYY-MM-DDTHH:MM:SS (localtime)
297* YYYY-MM-DDTHH:MM:SSZ (UTC)
c70a2119 298</PRE>
ce838977 299
c70a2119 300<P>
ce838977 301You can omit the YYYY-MM-DD, and then it refers to the current day. However
c70a2119 302note that <SAMP>`?date=16:00:00'</SAMP> refers to 4PM on the current day -- this may be
ce838977
PG
303in the future and so unlikely to useful.
304
ae98a915 305</P>
c70a2119 306<P>
ce838977 307You use this by adding the ?date= to the end of the URL for the stream.
c70a2119
FB
308For example: <SAMP>`http://localhost:8080/test.asf?date=2002-07-26T23:05:00'</SAMP>.
309
ae98a915 310</P>
c70a2119 311<P><HR><P>
ae98a915
PG
312This document was generated on 19 November 2002 using the
313<A HREF="http://wwwcn.cern.ch/dci/texi2html/">texi2html</A>
314translator version 1.51.</P>
c70a2119
FB
315</BODY>
316</HTML>