More accurate value for log2(10)
[libav.git] / doc / ffserver-doc.texi
CommitLineData
c70a2119 1\input texinfo @c -*- texinfo -*-
bdd3c092 2
c70a2119
FB
3@settitle FFserver Documentation
4@titlepage
5@sp 7
6@center @titlefont{FFserver Documentation}
7@sp 3
8@end titlepage
bdd3c092 9
bdd3c092 10
c70a2119 11@chapter Introduction
bdd3c092 12
e99c4e10 13@c man begin DESCRIPTION
c70a2119
FB
14FFserver is a streaming server for both audio and video. It supports
15several live feeds, streaming from files and time shifting on live feeds
16(you can seek to positions in the past on each live feed, provided you
17specify a big enough feed storage in ffserver.conf).
bdd3c092 18
60b51bb2
SS
19FFserver runs in daemon mode by default; that is, it puts itself in
20the background and detaches from its TTY, unless it is launched in
21debug mode or a NoDaemon option is specified in the configuration
22file.
23
c70a2119
FB
24This documentation covers only the streaming aspects of ffserver /
25ffmpeg. All questions about parameters for ffmpeg, codec questions,
e99c4e10 26etc. are not covered here. Read @file{ffmpeg-doc.html} for more
c70a2119 27information.
c70a2119 28
f26a60a0
SS
29@section How does it work?
30
31FFserver receives prerecorded files or FFM streams from some ffmpeg
32instance as input, then streams them over RTP/RTSP/HTTP.
33
34An ffserver instance will listen on some port as specified in the
35configuration file. You can launch one or more instances of ffmpeg and
36send one or more FFM streams to the port where ffserver is expecting
37to receive them. Alternately, you can make ffserver launch such ffmpeg
38instances at startup.
39
40Input streams are called feeds, and each one is specified by a <Feed>
41section in the configuration file.
42
43For each feed you can have different output streams in various
44formats, each one specified by a <Stream> section in the configuration
45file.
46
d45bad6c
SS
47@section Status stream
48
49FFserver supports an HTTP interface which exposes the current status
50of the server.
51
52Simply point your browser to the address of the special status stream
53specified in the configuration file.
54
55For example if you have:
56@example
57<Stream status.html>
58Format status
59
60# Only allow local people to get the status
61ACL allow localhost
62ACL allow 192.168.0.0 192.168.255.255
63</Stream>
64@end example
65
66then the server will post a page with the status information when
67the special stream @file{status.html} is requested.
68
c70a2119 69@section What can this do?
bdd3c092
PG
70
71When properly configured and running, you can capture video and audio in real
72time from a suitable capture card, and stream it out over the Internet to
73either Windows Media Player or RealAudio player (with some restrictions).
74
75It can also stream from files, though that is currently broken. Very often, a
76web server can be used to serve up the files just as well.
77
ae98a915
PG
78It can stream prerecorded video from .ffm files, though it is somewhat tricky
79to make it work correctly.
80
c70a2119 81@section What do I need?
bdd3c092 82
c27c66c3 83I use Linux on a 900 MHz Duron with a cheapo Bt848 based TV capture card. I'm
b1e4528b
DB
84using stock Linux 2.4.17 with the stock drivers. [Actually that isn't true,
85I needed some special drivers for my motherboard-based sound card.]
bdd3c092
PG
86
87I understand that FreeBSD systems work just fine as well.
88
c70a2119 89@section How do I make it work?
bdd3c092
PG
90
91First, build the kit. It *really* helps to have installed LAME first. Then when
1cc60c47
DB
92you run the ffserver ./configure, make sure that you have the
93@code{--enable-libmp3lame} flag turned on.
bdd3c092 94
3e4a1028 95LAME is important as it allows for streaming audio to Windows Media Player.
b1e4528b 96Don't ask why the other audio types do not work.
bdd3c092 97
bc2869f6
SS
98As a simple test, just run the following two command lines where INPUTFILE
99is some file which you can decode with ffmpeg:
bdd3c092 100
c70a2119 101@example
bdd3c092 102./ffserver -f doc/ffserver.conf &
bc2869f6 103./ffmpeg -i INPUTFILE http://localhost:8090/feed1.ffm
c70a2119 104@end example
bdd3c092 105
b1e4528b 106At this point you should be able to go to your Windows machine and fire up
115329f1 107Windows Media Player (WMP). Go to Open URL and enter
bdd3c092 108
c70a2119 109@example
bdd3c092 110 http://<linuxbox>:8090/test.asf
c70a2119 111@end example
bdd3c092 112
115329f1 113You should (after a short delay) see video and hear audio.
bdd3c092 114
96c7b535 115WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
b1e4528b
DB
116transfer the entire file before starting to play.
117The same is true of AVI files.
96c7b535 118
c70a2119 119@section What happens next?
bdd3c092 120
115329f1 121You should edit the ffserver.conf file to suit your needs (in terms of
bdd3c092
PG
122frame rates etc). Then install ffserver and ffmpeg, write a script to start
123them up, and off you go.
124
c70a2119 125@section Troubleshooting
bdd3c092 126
b1e4528b 127@subsection I don't hear any audio, but video is fine.
bdd3c092 128
b1e4528b
DB
129Maybe you didn't install LAME, or got your ./configure statement wrong. Check
130the ffmpeg output to see if a line referring to MP3 is present. If not, then
bdd3c092 131your configuration was incorrect. If it is, then maybe your wiring is not
115329f1 132set up correctly. Maybe the sound card is not getting data from the right
bdd3c092 133input source. Maybe you have a really awful audio interface (like I do)
115329f1
DB
134that only captures in stereo and also requires that one channel be flipped.
135If you are one of these people, then export 'AUDIO_FLIP_LEFT=1' before
bdd3c092
PG
136starting ffmpeg.
137
c70a2119 138@subsection The audio and video loose sync after a while.
bdd3c092
PG
139
140Yes, they do.
141
c70a2119 142@subsection After a long while, the video update rate goes way down in WMP.
bdd3c092
PG
143
144Yes, it does. Who knows why?
145
c70a2119 146@subsection WMP 6.4 behaves differently to WMP 7.
9cfe269e
PG
147
148Yes, it does. Any thoughts on this would be gratefully received. These
149differences extend to embedding WMP into a web page. [There are two
758b4bcd
DB
150object IDs that you can use: The old one, which does not play well, and
151the new one, which does (both tested on the same system). However,
9cfe269e
PG
152I suspect that the new one is not available unless you have installed WMP 7].
153
c70a2119 154@section What else can it do?
bdd3c092 155
ae98a915 156You can replay video from .ffm files that was recorded earlier.
115329f1 157However, there are a number of caveats, including the fact that the
ae98a915 158ffserver parameters must match the original parameters used to record the
3e4a1028 159file. If they do not, then ffserver deletes the file before recording into it.
b1e4528b 160(Now that I write this, it seems broken).
bdd3c092
PG
161
162You can fiddle with many of the codec choices and encoding parameters, and
163there are a bunch more parameters that you cannot control. Post a message
b1e4528b 164to the mailing list if there are some 'must have' parameters. Look in
bdd3c092
PG
165ffserver.conf for a list of the currently available controls.
166
b1e4528b
DB
167It will automatically generate the ASX or RAM files that are often used
168in browsers. These files are actually redirections to the underlying ASF
169or RM file. The reason for this is that the browser often fetches the
9cfe269e
PG
170entire file before starting up the external viewer. The redirection files
171are very small and can be transferred quickly. [The stream itself is
115329f1 172often 'infinite' and thus the browser tries to download it and never
9cfe269e
PG
173finishes.]
174
c70a2119 175@section Tips
bdd3c092 176
3e4a1028 177* When you connect to a live stream, most players (WMP, RA, etc) want to
bdd3c092
PG
178buffer a certain number of seconds of material so that they can display the
179signal continuously. However, ffserver (by default) starts sending data
b1e4528b 180in realtime. This means that there is a pause of a few seconds while the
bdd3c092 181buffering is being done by the player. The good news is that this can be
3e4a1028 182cured by adding a '?buffer=5' to the end of the URL. This means that the
115329f1 183stream should start 5 seconds in the past -- and so the first 5 seconds
b1e4528b 184of the stream are sent as fast as the network will allow. It will then
bdd3c092 185slow down to real time. This noticeably improves the startup experience.
9cfe269e
PG
186
187You can also add a 'Preroll 15' statement into the ffserver.conf that will
188add the 15 second prebuffering on all requests that do not otherwise
189specify a time. In addition, ffserver will skip frames until a key_frame
190is found. This further reduces the startup delay by not transferring data
191that will be discarded.
192
193* You may want to adjust the MaxBandwidth in the ffserver.conf to limit
194the amount of bandwidth consumed by live streams.
ce838977 195
c70a2119 196@section Why does the ?buffer / Preroll stop working after a time?
ce838977
PG
197
198It turns out that (on my machine at least) the number of frames successfully
199grabbed is marginally less than the number that ought to be grabbed. This
b1e4528b
DB
200means that the timestamp in the encoded data stream gets behind realtime.
201This means that if you say 'Preroll 10', then when the stream gets 10
202or more seconds behind, there is no Preroll left.
ce838977 203
115329f1 204Fixing this requires a change in the internals of how timestamps are
ce838977
PG
205handled.
206
c70a2119 207@section Does the @code{?date=} stuff work.
ce838977 208
b1e4528b
DB
209Yes (subject to the limitation outlined above). Also note that whenever you
210start ffserver, it deletes the ffm file (if any parameters have changed),
115329f1 211thus wiping out what you had recorded before.
ce838977 212
c70a2119 213The format of the @code{?date=xxxxxx} is fairly flexible. You should use one
ce838977
PG
214of the following formats (the 'T' is literal):
215
c70a2119 216@example
ce838977
PG
217* YYYY-MM-DDTHH:MM:SS (localtime)
218* YYYY-MM-DDTHH:MM:SSZ (UTC)
c70a2119 219@end example
ce838977 220
115329f1 221You can omit the YYYY-MM-DD, and then it refers to the current day. However
3e4a1028
DB
222note that @samp{?date=16:00:00} refers to 16:00 on the current day -- this
223may be in the future and so is unlikely to be useful.
ce838977
PG
224
225You use this by adding the ?date= to the end of the URL for the stream.
c70a2119 226For example: @samp{http://localhost:8080/test.asf?date=2002-07-26T23:05:00}.
fb6b04aa 227@c man end
c70a2119 228
e99c4e10
FB
229@chapter Invocation
230@section Syntax
115329f1 231@example
e99c4e10
FB
232@c man begin SYNOPSIS
233ffserver [options]
234@c man end
235@end example
236
237@section Options
238@c man begin OPTIONS
8b9da8b5 239
5f6cb6eb 240@include fftools-common-opts.texi
8b9da8b5
SS
241
242@table @option
a19caa0f 243@item -f @var{configfile}
b1e4528b 244Use @file{configfile} instead of @file{/etc/ffserver.conf}.
dea7da10
SS
245@item -n
246Enable no-launch mode. This option disables all the Launch directives
247within the various <Stream> sections. FFserver will not launch any
248ffmpeg instance, so you will have to launch them manually.
c1bb8f97
SS
249@item -d
250Enable debug mode. This option increases log verbosity, directs log
d6fbdcec 251messages to stdout and causes ffserver to run in the foreground
c1bb8f97 252rather than as a daemon.
e99c4e10
FB
253@end table
254@c man end
255
256@ignore
257
831ec935 258@setfilename ffserver
e99c4e10
FB
259@settitle FFserver video server
260
261@c man begin SEEALSO
5ee03c86 262ffmpeg(1), ffplay(1), the @file{ffmpeg/doc/ffserver.conf} example and
b1e4528b 263the HTML documentation of @file{ffmpeg}.
e99c4e10
FB
264@c man end
265
266@c man begin AUTHOR
267Fabrice Bellard
268@c man end
269
270@end ignore
271
c70a2119 272@bye