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