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