doc/ffserver: specify default value for Preroll
[ffmpeg.git] / doc / ffserver.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @settitle ffserver Documentation
4 @titlepage
5 @center @titlefont{ffserver Documentation}
6 @end titlepage
7
8 @top
9
10 @contents
11
12 @chapter Synopsis
13
14 ffserver [@var{options}]
15
16 @chapter Description
17 @c man begin DESCRIPTION
18
19 @command{ffserver} is a streaming server for both audio and video. It
20 supports several live feeds, streaming from files and time shifting on
21 live feeds (you can seek to positions in the past on each live feed,
22 provided you specify a big enough feed storage in
23 @file{ffserver.conf}).
24
25 @command{ffserver} receives prerecorded files or FFM streams from some
26 @command{ffmpeg} instance as input, then streams them over
27 RTP/RTSP/HTTP.
28
29 An @command{ffserver} instance will listen on some port as specified
30 in the configuration file. You can launch one or more instances of
31 @command{ffmpeg} and send one or more FFM streams to the port where
32 ffserver is expecting to receive them. Alternately, you can make
33 @command{ffserver} launch such @command{ffmpeg} instances at startup.
34
35 Input streams are called feeds, and each one is specified by a
36 @code{<Feed>} section in the configuration file.
37
38 For each feed you can have different output streams in various
39 formats, each one specified by a @code{<Stream>} section in the
40 configuration file.
41
42 @section Status stream
43
44 @command{ffserver} supports an HTTP interface which exposes the
45 current status of the server.
46
47 Simply point your browser to the address of the special status stream
48 specified in the configuration file.
49
50 For example if you have:
51 @example
52 <Stream status.html>
53 Format status
54
55 # Only allow local people to get the status
56 ACL allow localhost
57 ACL allow 192.168.0.0 192.168.255.255
58 </Stream>
59 @end example
60
61 then the server will post a page with the status information when
62 the special stream @file{status.html} is requested.
63
64 @section How do I make it work?
65
66 First, build the kit. It *really* helps to have installed LAME first. Then when
67 you run the ffserver ./configure, make sure that you have the
68 @code{--enable-libmp3lame} flag turned on.
69
70 LAME is important as it allows for streaming audio to Windows Media Player.
71 Don't ask why the other audio types do not work.
72
73 As a simple test, just run the following two command lines where INPUTFILE
74 is some file which you can decode with ffmpeg:
75
76 @example
77 ffserver -f doc/ffserver.conf &
78 ffmpeg -i INPUTFILE http://localhost:8090/feed1.ffm
79 @end example
80
81 At this point you should be able to go to your Windows machine and fire up
82 Windows Media Player (WMP). Go to Open URL and enter
83
84 @example
85     http://<linuxbox>:8090/test.asf
86 @end example
87
88 You should (after a short delay) see video and hear audio.
89
90 WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
91 transfer the entire file before starting to play.
92 The same is true of AVI files.
93
94 @section What happens next?
95
96 You should edit the ffserver.conf file to suit your needs (in terms of
97 frame rates etc). Then install ffserver and ffmpeg, write a script to start
98 them up, and off you go.
99
100 @section What else can it do?
101
102 You can replay video from .ffm files that was recorded earlier.
103 However, there are a number of caveats, including the fact that the
104 ffserver parameters must match the original parameters used to record the
105 file. If they do not, then ffserver deletes the file before recording into it.
106 (Now that I write this, it seems broken).
107
108 You can fiddle with many of the codec choices and encoding parameters, and
109 there are a bunch more parameters that you cannot control. Post a message
110 to the mailing list if there are some 'must have' parameters. Look in
111 ffserver.conf for a list of the currently available controls.
112
113 It will automatically generate the ASX or RAM files that are often used
114 in browsers. These files are actually redirections to the underlying ASF
115 or RM file. The reason for this is that the browser often fetches the
116 entire file before starting up the external viewer. The redirection files
117 are very small and can be transferred quickly. [The stream itself is
118 often 'infinite' and thus the browser tries to download it and never
119 finishes.]
120
121 @section Tips
122
123 * When you connect to a live stream, most players (WMP, RA, etc) want to
124 buffer a certain number of seconds of material so that they can display the
125 signal continuously. However, ffserver (by default) starts sending data
126 in realtime. This means that there is a pause of a few seconds while the
127 buffering is being done by the player. The good news is that this can be
128 cured by adding a '?buffer=5' to the end of the URL. This means that the
129 stream should start 5 seconds in the past -- and so the first 5 seconds
130 of the stream are sent as fast as the network will allow. It will then
131 slow down to real time. This noticeably improves the startup experience.
132
133 You can also add a 'Preroll 15' statement into the ffserver.conf that will
134 add the 15 second prebuffering on all requests that do not otherwise
135 specify a time. In addition, ffserver will skip frames until a key_frame
136 is found. This further reduces the startup delay by not transferring data
137 that will be discarded.
138
139 * You may want to adjust the MaxBandwidth in the ffserver.conf to limit
140 the amount of bandwidth consumed by live streams.
141
142 @section Why does the ?buffer / Preroll stop working after a time?
143
144 It turns out that (on my machine at least) the number of frames successfully
145 grabbed is marginally less than the number that ought to be grabbed. This
146 means that the timestamp in the encoded data stream gets behind realtime.
147 This means that if you say 'Preroll 10', then when the stream gets 10
148 or more seconds behind, there is no Preroll left.
149
150 Fixing this requires a change in the internals of how timestamps are
151 handled.
152
153 @section Does the @code{?date=} stuff work.
154
155 Yes (subject to the limitation outlined above). Also note that whenever you
156 start ffserver, it deletes the ffm file (if any parameters have changed),
157 thus wiping out what you had recorded before.
158
159 The format of the @code{?date=xxxxxx} is fairly flexible. You should use one
160 of the following formats (the 'T' is literal):
161
162 @example
163 * YYYY-MM-DDTHH:MM:SS     (localtime)
164 * YYYY-MM-DDTHH:MM:SSZ    (UTC)
165 @end example
166
167 You can omit the YYYY-MM-DD, and then it refers to the current day. However
168 note that @samp{?date=16:00:00} refers to 16:00 on the current day -- this
169 may be in the future and so is unlikely to be useful.
170
171 You use this by adding the ?date= to the end of the URL for the stream.
172 For example:   @samp{http://localhost:8080/test.asf?date=2002-07-26T23:05:00}.
173 @c man end
174
175 @section What is FFM, FFM2
176
177 FFM and FFM2 are formats used by ffserver. They allow storing a wide variety of
178 video and audio streams and encoding options, and can store a moving time segment
179 of an infinite movie or a whole movie.
180
181 FFM is version specific, and there is limited compatibility of FFM files
182 generated by one version of ffmpeg/ffserver and another version of
183 ffmpeg/ffserver. It may work but it is not guaranteed to work.
184
185 FFM2 is extensible while maintaining compatibility and should work between
186 differing versions of tools. FFM2 is the default.
187
188 @chapter Options
189 @c man begin OPTIONS
190
191 @include fftools-common-opts.texi
192
193 @section Main options
194
195 @table @option
196 @item -f @var{configfile}
197 Use @file{configfile} instead of @file{/etc/ffserver.conf}.
198
199 @item -n
200 Enable no-launch mode. This option disables all the @code{Launch}
201 directives within the various @code{<Stream>} sections. Since
202 @command{ffserver} will not launch any @command{ffmpeg} instances, you
203 will have to launch them manually.
204
205 @item -d
206 Enable debug mode. This option increases log verbosity, directs log
207 messages to stdout.
208 @end table
209
210 @chapter Configuration file syntax
211
212 @command{ffserver} reads a configuration file containing global
213 options and settings for each stream and feed.
214
215 The configuration file consists of global options and dedicated
216 sections, which must be introduced by "<@var{SECTION_NAME}
217 @var{ARGS}>" on a separate line and must be terminated by a line in
218 the form "</@var{SECTION_NAME}>". @var{ARGS} is optional.
219
220 Currently the following sections are recognized: @samp{Feed},
221 @samp{Stream}, @samp{Redirect}.
222
223 A line starting with @code{#} is ignored and treated as a comment.
224
225 @section Global options
226 @table @option
227 @item Port @var{port_number}
228 @item RTSPPort @var{port_number}
229
230 Set TCP port number on which the HTTP/RTSP server is listening. You
231 must select a different port from your standard HTTP web server if it
232 is running on the same computer.
233
234 If not specified, no corresponding server will be created.
235
236 @item BindAddress @var{ip_address}
237 @item RTSPBindAddress @var{ip_address}
238 Set address on which the HTTP/RTPS server is bound. Only useful if you
239 have several network interfaces.
240
241 @item MaxHTTPConnections @var{n}
242 Set number of simultaneous HTTP connections that can be handled. It
243 has to be defined @emph{before} the @option{MaxClients} parameter,
244 since it defines the @option{MaxClients} maximum limit.
245
246 Default value is 2000.
247
248 @item MaxClients @var{n}
249 Set number of simultaneous requests that can be handled. Since
250 @command{ffserver} is very fast, it is more likely that you will want
251 to leave this high and use @option{MaxBandwidth}.
252
253 Default value is 5.
254
255 @item MaxBandwidth @var{kbps}
256 Set the maximum amount of kbit/sec that you are prepared to consume
257 when streaming to clients.
258
259 Default value is 1000.
260
261 @item CustomLog @var{filename}
262 Set access log file (uses standard Apache log file format).
263
264 '-' is the standard output.
265
266 @item NoDaemon
267 Set no-daemon mode. This option is currently ignored since now
268 @command{ffserver} will work in no-daemon mode, and is deprecated.
269
270 @end table
271
272 @section ACL syntax
273 An ACL (Access Control List) specifies the address which are allowed
274 to access a given stream, or to write a given feed.
275
276 It accepts the folling forms
277 @itemize
278 @item
279 Allow/deny access to @var{address}.
280 @example
281 ACL ALLOW <address>
282 ACL DENY <address>
283 @end example
284
285 @item
286 Allow/deny access to ranges of addresses from @var{first_address} to
287 @var{last_address}.
288 @example
289 ACL ALLOW <first_address> <last_address>
290 ACL DENY <first_address> <last_address>
291 @end example
292 @end itemize
293
294 You can repeat the ACL allow/deny as often as you like. It is on a per
295 stream basis. The first match defines the action. If there are no matches,
296 then the default is the inverse of the last ACL statement.
297
298 Thus 'ACL allow localhost' only allows access from localhost.
299 'ACL deny 1.0.0.0 1.255.255.255' would deny the whole of network 1 and
300 allow everybody else.
301
302 @section Feed section
303
304 A Feed section defines a feed provided to @command{ffserver}.
305
306 Each live feed contains one video and/or audio sequence coming from an
307 @command{ffmpeg} encoder or another @command{ffserver}. This sequence
308 may be encoded simultaneously with several codecs at several
309 resolutions.
310
311 A feed instance specification is introduced by a line in the form:
312 @example
313 <Feed FEED_FILENAME>
314 @end example
315
316 where @var{FEED_FILENAME} specifies the unique name of the FFM stream.
317
318 The following options are recognized within a Feed section.
319
320 @table @option
321 @item File @var{filename}
322 Set the path where the file is stored on disk.
323
324 @item FileMaxSize @var{size}
325 Set maximum size of the feed. 0 means unlimited.
326
327 @item ReadOnlyFile @var{filename}
328 Mark the file as readonly and it will not be deleted or updated.
329
330 @item Launch
331
332 @item ACL
333 Specify the list of IP address which are allowed or denied to write
334 the feed. Multiple ACL options can be specified.
335 @end table
336
337 @section Stream section
338
339 A Stream section defines a stream provided by @command{ffserver}, and
340 identified by a single name.
341
342 The stream is sent when answering a request containing the stream
343 name.
344
345 A stream section must be introduced by the line:
346 @example
347 <Stream STREAM_NAME>
348 @end example
349
350 where @var{STREAM_NAME} specifies the unique name of the stream.
351
352 The following options are recognized within a Stream section.
353
354 @table @option
355 @item Feed @var{feed_name}
356 Set the input feed.
357
358 Must be specified.
359
360 @item Format @var{format_name}
361 Set the format of the stream.
362
363 Must be the name of a format recognized by FFmpeg.
364
365 @item AudioBitRate @var{rate}
366 Set bitrate for the audio stream in KB per second.
367
368 @item AudioChannels @var{n}
369 Set number of audio channels.
370
371 @item AudioSampleRate @var{n}
372 Set sampling frequency for audio. When using low bitrates, you should
373 lower this frequency to 22050 or 11025. The supported frequencies
374 depend on the selected audio codec.
375
376 @item VideoBitRate @var{n}
377 Set bitrate for the video stream in KB per second.
378
379 @item VideoBitRateRange @var{range}
380 Set video bitrate range.
381
382 @item VideoBitRateRangeTolerance @var{n}
383
384 @item PixelFormat
385 Set video pixel format.
386
387 @item VideoBufferSize @var{n}
388 Set ratecontrol buffer size.
389
390 @item VideoFrameRate @var{n}
391 Set number of video frames per second.
392
393 @item VideoSize
394 Set size of the video frame, must be an abbreviation or in the form
395 @var{W}x@var{H}.  See @ref{video size syntax,,the Video size section
396 in the ffmpeg-utils(1) manual,ffmpeg-utils}.
397
398 Default value is @code{160x128}.
399
400 @item VideoIntraOnly
401 Transmit only intra frames (useful for low bitrates, but kills frame rate).
402
403 @item VideoGopSize @var{n}
404 If non-intra only, an intra frame is transmitted every VideoGopSize
405 frames. Video synchronization can only begin at an intra frame.
406
407 @item VideoHighQuality
408 @item Video4MotionVector
409
410 @item AudioCodec @var{codec_name}
411 @item VideoCodec @var{codec_name}
412 Set audio/video codec.
413
414 @item NoAudio
415 @item NoVideo
416 Suppress audio/video.
417
418 @item VideoQMin @var{n}
419 @item VideoQMax @var{n}
420 Set video qmin/qmax.
421
422 @item AVOptionAudio @var{option} @var{value}
423 @item AVOptionVideo @var{option} @var{value}
424 Set generic option for audio/video stream.
425
426 @item AVPresetAudio @var{preset}
427 @item AVOptionVideo @var{preset}
428 Set preset for audio/video stream.
429
430 @var{preset} must be the path of a preset file.
431
432 @item Preroll @var{n}
433 Set this to the number of seconds backwards in time to start. Note that
434 most players will buffer 5-10 seconds of video, and also you need to allow
435 for a keyframe to appear in the data stream.
436
437 Default value is 0.
438
439 @item ACL @var{spec}
440 Set ACL for the stream.
441
442 @item Author @var{value}
443 @item Comment @var{value}
444 @item Copyright @var{value}
445 @item Title @var{value}
446 Set metadata corresponding to the option.
447
448 @item StartSendOnKey
449 Do not send stream until it gets the first key frame. By default
450 @command{ffserver} will send data immediately.
451
452 @item FaviconURL @var{url}
453 Set favicon (favourite icon) for the server status page. It is ignored
454 for regular streams.
455 @end table
456
457 @subsection Server status stream
458
459 A server status stream is a special stream which is used to show
460 statistics about the @command{ffserver} operations.
461
462 It must be specified setting the option @option{Format} to
463 @code{status}.
464
465 @section Redirect section
466
467 A redirect section specifies where to redirect the requested URL to
468 another page.
469
470 A redirect section must be introduced by the line:
471 @example
472 <Redirect NAME>
473 @end example
474
475 where @var{NAME} is the name of the page which should be redirected.
476
477 It only accepts the option @option{URL}, which specify the redirection
478 URL.
479
480 @chapter Stream examples
481
482 @itemize
483 @item
484 Multipart JPEG
485 @example
486 <Stream test.mjpg>
487 Feed feed1.ffm
488 Format mpjpeg
489 VideoFrameRate 2
490 VideoIntraOnly
491 NoAudio
492 Strict -1
493 </Stream>
494 @end example
495
496 @item
497 Single JPEG
498 @example
499 <Stream test.jpg>
500 Feed feed1.ffm
501 Format jpeg
502 VideoFrameRate 2
503 VideoIntraOnly
504 #VideoSize 352x240
505 NoAudio
506 Strict -1
507 </Stream>
508 @end example
509
510 @item
511 Flash
512 @example
513 <Stream test.swf>
514 Feed feed1.ffm
515 Format swf
516 VideoFrameRate 2
517 VideoIntraOnly
518 NoAudio
519 </Stream>
520 @end example
521
522 @item
523 ASF compatible
524 @example
525 <Stream test.asf>
526 Feed feed1.ffm
527 Format asf
528 VideoFrameRate 15
529 VideoSize 352x240
530 VideoBitRate 256
531 VideoBufferSize 40
532 VideoGopSize 30
533 AudioBitRate 64
534 StartSendOnKey
535 </Stream>
536 @end example
537
538 @item
539 MP3 audio
540 @example
541 <Stream test.mp3>
542 Feed feed1.ffm
543 Format mp2
544 AudioCodec mp3
545 AudioBitRate 64
546 AudioChannels 1
547 AudioSampleRate 44100
548 NoVideo
549 </Stream>
550 @end example
551
552 @item
553 Ogg Vorbis audio:
554 @example
555 <Stream test.ogg>
556 Feed feed1.ffm
557 Title "Stream title"
558 AudioBitRate 64
559 AudioChannels 2
560 AudioSampleRate 44100
561 NoVideo
562 </Stream>
563 @end example
564
565 @item
566 Real with audio only at 32 kbits
567 @example
568 <Stream test.ra>
569 Feed feed1.ffm
570 Format rm
571 AudioBitRate 32
572 NoVideo
573 NoAudio
574 </Stream>
575 @end example
576
577 @item
578 Real with audio and video at 64 kbits
579 @example
580 <Stream test.rm>
581 Feed feed1.ffm
582 Format rm
583 AudioBitRate 32
584 VideoBitRate 128
585 VideoFrameRate 25
586 VideoGopSize 25
587 NoAudio
588 </Stream>
589 @end example
590
591 @item
592 For stream coming from a file: you only need to set the input filename
593 and optionally a new format.
594
595 @example
596 <Stream file.rm>
597 File "/usr/local/httpd/htdocs/tlive.rm"
598 NoAudio
599 </Stream>
600 @end example
601
602 @example
603 <Stream file.asf>
604 File "/usr/local/httpd/htdocs/test.asf"
605 NoAudio
606 Author "Me"
607 Copyright "Super MegaCorp"
608 Title "Test stream from disk"
609 Comment "Test comment"
610 </Stream>
611 @end example
612 @end itemize
613
614 @c man end
615
616 @include config.texi
617 @ifset config-all
618 @ifset config-avutil
619 @include utils.texi
620 @end ifset
621 @ifset config-avcodec
622 @include codecs.texi
623 @include bitstream_filters.texi
624 @end ifset
625 @ifset config-avformat
626 @include formats.texi
627 @include protocols.texi
628 @end ifset
629 @ifset config-avdevice
630 @include devices.texi
631 @end ifset
632 @ifset config-swresample
633 @include resampler.texi
634 @end ifset
635 @ifset config-swscale
636 @include scaler.texi
637 @end ifset
638 @ifset config-avfilter
639 @include filters.texi
640 @end ifset
641 @end ifset
642
643 @chapter See Also
644
645 @ifhtml
646 @ifset config-all
647 @url{ffserver.html,ffserver},
648 @end ifset
649 @ifset config-not-all
650 @url{ffserver-all.html,ffserver-all},
651 @end ifset
652 the @file{doc/ffserver.conf} example,
653 @url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe},
654 @url{ffmpeg-utils.html,ffmpeg-utils},
655 @url{ffmpeg-scaler.html,ffmpeg-scaler},
656 @url{ffmpeg-resampler.html,ffmpeg-resampler},
657 @url{ffmpeg-codecs.html,ffmpeg-codecs},
658 @url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters},
659 @url{ffmpeg-formats.html,ffmpeg-formats},
660 @url{ffmpeg-devices.html,ffmpeg-devices},
661 @url{ffmpeg-protocols.html,ffmpeg-protocols},
662 @url{ffmpeg-filters.html,ffmpeg-filters}
663 @end ifhtml
664
665 @ifnothtml
666 @ifset config-all
667 ffserver(1),
668 @end ifset
669 @ifset config-not-all
670 ffserver-all(1),
671 @end ifset
672 the @file{doc/ffserver.conf} example, ffmpeg(1), ffplay(1), ffprobe(1),
673 ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
674 ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),
675 ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1)
676 @end ifnothtml
677
678 @include authors.texi
679
680 @ignore
681
682 @setfilename ffserver
683 @settitle ffserver video server
684
685 @end ignore
686
687 @bye