doc/ffserver: remove "What can this do?" section
[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 @item -n
199 Enable no-launch mode. This option disables all the Launch directives
200 within the various <Stream> sections. Since ffserver will not launch
201 any ffmpeg instances, you will have to launch them manually.
202 @item -d
203 Enable debug mode. This option increases log verbosity, directs log
204 messages to stdout.
205 @end table
206
207 @chapter Configuration file syntax
208
209 @command{ffserver} reads a configuration file containing global
210 options and settings for each stream and feed.
211
212 The configuration file consists of global options and dedicated
213 sections, which must be introduced by "<@var{SECTION_NAME}
214 @var{ARGS}>" on a separate line and must be terminated by a line in
215 the form "</@var{SECTION_NAME}>". @var{ARGS} is optional.
216
217 Currently the following sections are recognized: @samp{Feed},
218 @samp{Stream}, @samp{Redirect}.
219
220 A line starting with @code{#} is ignored and treated as a comment.
221
222 @section Global options
223 @table @option
224 @item Port @var{port_number}
225 @item RTSPPort @var{port_number}
226
227 Set TCP port number on which the HTTP/RTSP server is listening. You
228 must select a different port from your standard HTTP web server if it
229 is running on the same computer.
230
231 If not specified, no corresponding server will be created.
232
233 @item BindAddress @var{ip_address}
234 @item RTSPBindAddress @var{ip_address}
235 Set address on which the HTTP/RTPS server is bound. Only useful if you
236 have several network interfaces.
237
238 @item MaxHTTPConnections @var{n}
239 Set number of simultaneous HTTP connections that can be handled. It
240 has to be defined @emph{before} the @option{MaxClients} parameter,
241 since it defines the @option{MaxClients} maximum limit.
242
243 Default value is 2000.
244
245 @item MaxClients @var{n}
246 Set number of simultaneous requests that can be handled. Since
247 @command{ffserver} is very fast, it is more likely that you will want
248 to leave this high and use @option{MaxBandwidth}.
249
250 Default value is 5.
251
252 @item MaxBandwidth @var{kbps}
253 Set the maximum amount of kbit/sec that you are prepared to consume
254 when streaming to clients.
255
256 Default value is 1000.
257
258 @item CustomLog @var{filename}
259 Set access log file (uses standard Apache log file format).
260
261 '-' is the standard output.
262 @end table
263
264 @section ACL syntax
265 An ACL (Access Control List) specifies the address which are allowed
266 to access a given stream, or to write a given feed.
267
268 It accepts the folling forms
269 @itemize
270 @item
271 Allow/deny access to @var{address}.
272 @example
273 ACL ALLOW <address>
274 ACL DENY <address>
275 @end example
276
277 @item
278 Allow/deny access to ranges of addresses from @var{first_address} to
279 @var{last_address}.
280 @example
281 ACL ALLOW <first_address> <last_address>
282 ACL DENY <first_address> <last_address>
283 @end example
284 @end itemize
285
286 You can repeat the ACL allow/deny as often as you like. It is on a per
287 stream basis. The first match defines the action. If there are no matches,
288 then the default is the inverse of the last ACL statement.
289
290 Thus 'ACL allow localhost' only allows access from localhost.
291 'ACL deny 1.0.0.0 1.255.255.255' would deny the whole of network 1 and
292 allow everybody else.
293
294 @section Feed section
295
296 A Feed section defines a feed provided to @command{ffserver}.
297
298 Each live feed contains one video and/or audio sequence coming from an
299 @command{ffmpeg} encoder or another @command{ffserver}. This sequence
300 may be encoded simultaneously with several codecs at several
301 resolutions.
302
303 A feed instance specification is introduced by a line in the form:
304 @example
305 <Feed FEED_FILENAME>
306 @end example
307
308 where @var{FEED_FILENAME} specifies the unique name of the FFM stream.
309
310 The following options are recognized within a Feed section.
311
312 @table @option
313 @item File @var{filename}
314 Set the path where the file is stored on disk.
315
316 @item FileMaxSize @var{size}
317 Set maximum size of the feed. 0 means unlimited.
318
319 @item ReadOnlyFile @var{filename}
320 Mark the file as readonly and it will not be deleted or updated.
321
322 @item Launch
323
324 @item ACL
325 Specify the list of IP address which are allowed or denied to write
326 the feed. Multiple ACL options can be specified.
327 @end table
328
329 @section Stream section
330
331 A Stream section defines a stream provided by @command{ffserver}, and
332 identified by a single name.
333
334 The stream is sent when answering a request containing the stream
335 name.
336
337 A stream section must be introduced by the line:
338 @example
339 <Stream STREAM_NAME>
340 @end example
341
342 where @var{STREAM_NAME} specifies the unique name of the stream.
343
344 The following options are recognized within a Stream section.
345
346 @table @option
347 @item Feed @var{feed_name}
348 Set the input feed.
349
350 Must be specified.
351
352 @item Format @var{format_name}
353 Set the format of the stream.
354
355 Must be the name of a format recognized by FFmpeg.
356
357 @item AudioBitRate @var{rate}
358 Set bitrate for the audio stream in KB per second.
359
360 @item AudioChannels @var{n}
361 Set number of audio channels.
362
363 @item AudioSampleRate @var{n}
364 Set sampling frequency for audio. When using low bitrates, you should
365 lower this frequency to 22050 or 11025. The supported frequencies
366 depend on the selected audio codec.
367
368 @item VideoBitRate @var{n}
369 Set bitrate for the video stream in KB per second.
370
371 @item VideoBitRateRange @var{range}
372 Set video bitrate range.
373
374 @item VideoBitRateRangeTolerance @var{n}
375
376 @item PixelFormat
377 Set video pixel format.
378
379 @item VideoBufferSize @var{n}
380 Set ratecontrol buffer size.
381
382 @item VideoFrameRate @var{n}
383 Set number of video frames per second.
384
385 @item VideoSize
386 Set size of the video frame, must be an abbreviation or in the form
387 @var{W}x@var{H}.  See @ref{video size syntax,,the Video size section
388 in the ffmpeg-utils(1) manual,ffmpeg-utils}.
389
390 Default value is @code{160x128}.
391
392 @item VideoIntraOnly
393 Transmit only intra frames (useful for low bitrates, but kills frame rate).
394
395 @item VideoGopSize @var{n}
396 If non-intra only, an intra frame is transmitted every VideoGopSize
397 frames. Video synchronization can only begin at an intra frame.
398
399 @item VideoHighQuality
400 @item Video4MotionVector
401
402 @item AudioCodec @var{codec_name}
403 @item VideoCodec @var{codec_name}
404 Set audio/video codec.
405
406 @item NoAudio
407 @item NoVideo
408 Suppress audio/video.
409
410 @item VideoQMin @var{n}
411 @item VideoQMax @var{n}
412 Set video qmin/qmax.
413
414 @item AVOptionAudio @var{option} @var{value}
415 @item AVOptionVideo @var{option} @var{value}
416 Set generic option for audio/video stream.
417
418 @item AVPresetAudio @var{preset}
419 @item AVOptionVideo @var{preset}
420 Set preset for audio/video stream.
421
422 @var{preset} must be the path of a preset file.
423
424 @item Preroll @var{n}
425 Set this to the number of seconds backwards in time to start. Note that
426 most players will buffer 5-10 seconds of video, and also you need to allow
427 for a keyframe to appear in the data stream.
428
429 @item ACL @var{spec}
430 Set ACL for the stream.
431
432 @item Author @var{value}
433 @item Comment @var{value}
434 @item Copyright @var{value}
435 @item Title @var{value}
436 Set metadata corresponding to the option.
437
438 @item StartSendOnKey
439 Do not send stream until it gets the first key frame. By default
440 @command{ffserver} will send data immediately.
441
442 @item FaviconURL @var{url}
443 Set favicon (favourite icon) for the server status page. It is ignored
444 for regular streams.
445 @end table
446
447 @subsection Server status stream
448
449 A server status stream is a special stream which is used to show
450 statistics about the @command{ffserver} operations.
451
452 It must be specified setting the option @option{Format} to
453 @code{status}.
454
455 @section Redirect section
456
457 A redirect section specifies where to redirect the requested URL to
458 another page.
459
460 A redirect section must be introduced by the line:
461 @example
462 <Redirect NAME>
463 @end example
464
465 where @var{NAME} is the name of the page which should be redirected.
466
467 It only accepts the option @option{URL}, which specify the redirection
468 URL.
469
470 @chapter Stream examples
471
472 @itemize
473 @item
474 Multipart JPEG
475 @example
476 <Stream test.mjpg>
477 Feed feed1.ffm
478 Format mpjpeg
479 VideoFrameRate 2
480 VideoIntraOnly
481 NoAudio
482 Strict -1
483 </Stream>
484 @end example
485
486 @item
487 Single JPEG
488 @example
489 <Stream test.jpg>
490 Feed feed1.ffm
491 Format jpeg
492 VideoFrameRate 2
493 VideoIntraOnly
494 #VideoSize 352x240
495 NoAudio
496 Strict -1
497 </Stream>
498 @end example
499
500 @item
501 Flash
502 @example
503 <Stream test.swf>
504 Feed feed1.ffm
505 Format swf
506 VideoFrameRate 2
507 VideoIntraOnly
508 NoAudio
509 </Stream>
510 @end example
511
512 @item
513 ASF compatible
514 @example
515 <Stream test.asf>
516 Feed feed1.ffm
517 Format asf
518 VideoFrameRate 15
519 VideoSize 352x240
520 VideoBitRate 256
521 VideoBufferSize 40
522 VideoGopSize 30
523 AudioBitRate 64
524 StartSendOnKey
525 </Stream>
526 @end example
527
528 @item
529 MP3 audio
530 @example
531 <Stream test.mp3>
532 Feed feed1.ffm
533 Format mp2
534 AudioCodec mp3
535 AudioBitRate 64
536 AudioChannels 1
537 AudioSampleRate 44100
538 NoVideo
539 </Stream>
540 @end example
541
542 @item
543 Ogg Vorbis audio:
544 @example
545 <Stream test.ogg>
546 Feed feed1.ffm
547 Title "Stream title"
548 AudioBitRate 64
549 AudioChannels 2
550 AudioSampleRate 44100
551 NoVideo
552 </Stream>
553 @end example
554
555 @item
556 Real with audio only at 32 kbits
557 @example
558 <Stream test.ra>
559 Feed feed1.ffm
560 Format rm
561 AudioBitRate 32
562 NoVideo
563 NoAudio
564 </Stream>
565 @end example
566
567 @item
568 Real with audio and video at 64 kbits
569 @example
570 <Stream test.rm>
571 Feed feed1.ffm
572 Format rm
573 AudioBitRate 32
574 VideoBitRate 128
575 VideoFrameRate 25
576 VideoGopSize 25
577 NoAudio
578 </Stream>
579 @end example
580
581 @item
582 For stream coming from a file: you only need to set the input filename
583 and optionally a new format.
584
585 @example
586 <Stream file.rm>
587 File "/usr/local/httpd/htdocs/tlive.rm"
588 NoAudio
589 </Stream>
590 @end example
591
592 @example
593 <Stream file.asf>
594 File "/usr/local/httpd/htdocs/test.asf"
595 NoAudio
596 Author "Me"
597 Copyright "Super MegaCorp"
598 Title "Test stream from disk"
599 Comment "Test comment"
600 </Stream>
601 @end example
602 @end itemize
603
604 @c man end
605
606 @include config.texi
607 @ifset config-all
608 @ifset config-avutil
609 @include utils.texi
610 @end ifset
611 @ifset config-avcodec
612 @include codecs.texi
613 @include bitstream_filters.texi
614 @end ifset
615 @ifset config-avformat
616 @include formats.texi
617 @include protocols.texi
618 @end ifset
619 @ifset config-avdevice
620 @include devices.texi
621 @end ifset
622 @ifset config-swresample
623 @include resampler.texi
624 @end ifset
625 @ifset config-swscale
626 @include scaler.texi
627 @end ifset
628 @ifset config-avfilter
629 @include filters.texi
630 @end ifset
631 @end ifset
632
633 @chapter See Also
634
635 @ifhtml
636 @ifset config-all
637 @url{ffserver.html,ffserver},
638 @end ifset
639 @ifset config-not-all
640 @url{ffserver-all.html,ffserver-all},
641 @end ifset
642 the @file{doc/ffserver.conf} example,
643 @url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe},
644 @url{ffmpeg-utils.html,ffmpeg-utils},
645 @url{ffmpeg-scaler.html,ffmpeg-scaler},
646 @url{ffmpeg-resampler.html,ffmpeg-resampler},
647 @url{ffmpeg-codecs.html,ffmpeg-codecs},
648 @url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters},
649 @url{ffmpeg-formats.html,ffmpeg-formats},
650 @url{ffmpeg-devices.html,ffmpeg-devices},
651 @url{ffmpeg-protocols.html,ffmpeg-protocols},
652 @url{ffmpeg-filters.html,ffmpeg-filters}
653 @end ifhtml
654
655 @ifnothtml
656 @ifset config-all
657 ffserver(1),
658 @end ifset
659 @ifset config-not-all
660 ffserver-all(1),
661 @end ifset
662 the @file{doc/ffserver.conf} example, ffmpeg(1), ffplay(1), ffprobe(1),
663 ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
664 ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),
665 ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1)
666 @end ifnothtml
667
668 @include authors.texi
669
670 @ignore
671
672 @setfilename ffserver
673 @settitle ffserver video server
674
675 @end ignore
676
677 @bye