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