1 \input texinfo @c -*- texinfo -*-
2 @documentencoding UTF-8
4 @settitle ffserver Documentation
6 @center @titlefont{ffserver Documentation}
15 ffserver [@var{options}]
18 @c man begin DESCRIPTION
20 @command{ffserver} is a streaming server for both audio and video.
21 It supports several live feeds, streaming from files and time shifting
22 on live feeds. You can seek to positions in the past on each live
23 feed, provided you specify a big enough feed storage.
25 @command{ffserver} is configured through a configuration file, which
26 is read at startup. If not explicitly specified, it will read from
27 @file{/etc/ffserver.conf}.
29 @command{ffserver} receives prerecorded files or FFM streams from some
30 @command{ffmpeg} instance as input, then streams them over
33 An @command{ffserver} instance will listen on some port as specified
34 in the configuration file. You can launch one or more instances of
35 @command{ffmpeg} and send one or more FFM streams to the port where
36 ffserver is expecting to receive them. Alternately, you can make
37 @command{ffserver} launch such @command{ffmpeg} instances at startup.
39 Input streams are called feeds, and each one is specified by a
40 @code{<Feed>} section in the configuration file.
42 For each feed you can have different output streams in various
43 formats, each one specified by a @code{<Stream>} section in the
46 @chapter Detailed description
48 @command{ffserver} works by forwarding streams encoded by
49 @command{ffmpeg}, or pre-recorded streams which are read from disk.
51 Precisely, @command{ffserver} acts as an HTTP server, accepting POST
52 requests from @command{ffmpeg} to acquire the stream to publish, and
53 serving RTSP clients or HTTP clients GET requests with the stream
56 A feed is an @ref{FFM} stream created by @command{ffmpeg}, and sent to
57 a port where @command{ffserver} is listening.
59 Each feed is identified by a unique name, corresponding to the name
60 of the resource published on @command{ffserver}, and is configured by
61 a dedicated @code{Feed} section in the configuration file.
63 The feed publish URL is given by:
65 http://@var{ffserver_ip_address}:@var{http_port}/@var{feed_name}
68 where @var{ffserver_ip_address} is the IP address of the machine where
69 @command{ffserver} is installed, @var{http_port} is the port number of
70 the HTTP server (configured through the @option{HTTPPort} option), and
71 @var{feed_name} is the name of the corresponding feed defined in the
74 Each feed is associated to a file which is stored on disk. This stored
75 file is used to send pre-recorded data to a player as fast as
76 possible when new content is added in real-time to the stream.
78 A "live-stream" or "stream" is a resource published by
79 @command{ffserver}, and made accessible through the HTTP protocol to
82 A stream can be connected to a feed, or to a file. In the first case,
83 the published stream is forwarded from the corresponding feed
84 generated by a running instance of @command{ffmpeg}, in the second
85 case the stream is read from a pre-recorded file.
87 Each stream is identified by a unique name, corresponding to the name
88 of the resource served by @command{ffserver}, and is configured by
89 a dedicated @code{Stream} section in the configuration file.
91 The stream access HTTP URL is given by:
93 http://@var{ffserver_ip_address}:@var{http_port}/@var{stream_name}[@var{options}]
96 The stream access RTSP URL is given by:
98 http://@var{ffserver_ip_address}:@var{rtsp_port}/@var{stream_name}[@var{options}]
101 @var{stream_name} is the name of the corresponding stream defined in
102 the configuration file. @var{options} is a list of options specified
103 after the URL which affects how the stream is served by
104 @command{ffserver}. @var{http_port} and @var{rtsp_port} are the HTTP
105 and RTSP ports configured with the options @var{HTTPPort} and
106 @var{RTSPPort} respectively.
108 In case the stream is associated to a feed, the encoding parameters
109 must be configured in the stream configuration. They are sent to
110 @command{ffmpeg} when setting up the encoding. This allows
111 @command{ffserver} to define the encoding parameters used by
112 the @command{ffmpeg} encoders.
114 The @command{ffmpeg} @option{override_ffserver} commandline option
115 allows one to override the encoding parameters set by the server.
117 Multiple streams can be connected to the same feed.
119 For example, you can have a situation described by the following
125 ffmpeg 1 -----| feed 1 |-----| stream 1 |
126 \ |_________|\ |__________|
133 \ _________ __________
135 \| feed 2 |-----| stream 3 |
136 |_________| |__________|
140 ffmpeg 2 -----| feed 3 |-----| stream 4 |
141 |_________| |__________|
145 | file 1 |-----| stream 5 |
146 |_________| |__________|
151 @section FFM, FFM2 formats
153 FFM and FFM2 are formats used by ffserver. They allow storing a wide variety of
154 video and audio streams and encoding options, and can store a moving time segment
155 of an infinite movie or a whole movie.
157 FFM is version specific, and there is limited compatibility of FFM files
158 generated by one version of ffmpeg/ffserver and another version of
159 ffmpeg/ffserver. It may work but it is not guaranteed to work.
161 FFM2 is extensible while maintaining compatibility and should work between
162 differing versions of tools. FFM2 is the default.
164 @section Status stream
166 @command{ffserver} supports an HTTP interface which exposes the
167 current status of the server.
169 Simply point your browser to the address of the special status stream
170 specified in the configuration file.
172 For example if you have:
177 # Only allow local people to get the status
179 ACL allow 192.168.0.0 192.168.255.255
183 then the server will post a page with the status information when
184 the special stream @file{status.html} is requested.
186 @section How do I make it work?
188 As a simple test, just run the following two command lines where INPUTFILE
189 is some file which you can decode with ffmpeg:
192 ffserver -f doc/ffserver.conf &
193 ffmpeg -i INPUTFILE http://localhost:8090/feed1.ffm
196 At this point you should be able to go to your Windows machine and fire up
197 Windows Media Player (WMP). Go to Open URL and enter
200 http://<linuxbox>:8090/test.asf
203 You should (after a short delay) see video and hear audio.
205 WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
206 transfer the entire file before starting to play.
207 The same is true of AVI files.
209 You should edit the @file{ffserver.conf} file to suit your needs (in
210 terms of frame rates etc). Then install @command{ffserver} and
211 @command{ffmpeg}, write a script to start them up, and off you go.
213 @section What else can it do?
215 You can replay video from .ffm files that was recorded earlier.
216 However, there are a number of caveats, including the fact that the
217 ffserver parameters must match the original parameters used to record the
218 file. If they do not, then ffserver deletes the file before recording into it.
219 (Now that I write this, it seems broken).
221 You can fiddle with many of the codec choices and encoding parameters, and
222 there are a bunch more parameters that you cannot control. Post a message
223 to the mailing list if there are some 'must have' parameters. Look in
224 ffserver.conf for a list of the currently available controls.
226 It will automatically generate the ASX or RAM files that are often used
227 in browsers. These files are actually redirections to the underlying ASF
228 or RM file. The reason for this is that the browser often fetches the
229 entire file before starting up the external viewer. The redirection files
230 are very small and can be transferred quickly. [The stream itself is
231 often 'infinite' and thus the browser tries to download it and never
236 * When you connect to a live stream, most players (WMP, RA, etc) want to
237 buffer a certain number of seconds of material so that they can display the
238 signal continuously. However, ffserver (by default) starts sending data
239 in realtime. This means that there is a pause of a few seconds while the
240 buffering is being done by the player. The good news is that this can be
241 cured by adding a '?buffer=5' to the end of the URL. This means that the
242 stream should start 5 seconds in the past -- and so the first 5 seconds
243 of the stream are sent as fast as the network will allow. It will then
244 slow down to real time. This noticeably improves the startup experience.
246 You can also add a 'Preroll 15' statement into the ffserver.conf that will
247 add the 15 second prebuffering on all requests that do not otherwise
248 specify a time. In addition, ffserver will skip frames until a key_frame
249 is found. This further reduces the startup delay by not transferring data
250 that will be discarded.
252 @section Why does the ?buffer / Preroll stop working after a time?
254 It turns out that (on my machine at least) the number of frames successfully
255 grabbed is marginally less than the number that ought to be grabbed. This
256 means that the timestamp in the encoded data stream gets behind realtime.
257 This means that if you say 'Preroll 10', then when the stream gets 10
258 or more seconds behind, there is no Preroll left.
260 Fixing this requires a change in the internals of how timestamps are
263 @section Does the @code{?date=} stuff work.
265 Yes (subject to the limitation outlined above). Also note that whenever you
266 start ffserver, it deletes the ffm file (if any parameters have changed),
267 thus wiping out what you had recorded before.
269 The format of the @code{?date=xxxxxx} is fairly flexible. You should use one
270 of the following formats (the 'T' is literal):
273 * YYYY-MM-DDTHH:MM:SS (localtime)
274 * YYYY-MM-DDTHH:MM:SSZ (UTC)
277 You can omit the YYYY-MM-DD, and then it refers to the current day. However
278 note that @samp{?date=16:00:00} refers to 16:00 on the current day -- this
279 may be in the future and so is unlikely to be useful.
281 You use this by adding the ?date= to the end of the URL for the stream.
282 For example: @samp{http://localhost:8080/test.asf?date=2002-07-26T23:05:00}.
288 @include fftools-common-opts.texi
290 @section Main options
293 @item -f @var{configfile}
294 Read configuration file @file{configfile}. If not specified it will
295 read by default from @file{/etc/ffserver.conf}.
298 Enable no-launch mode. This option disables all the @code{Launch}
299 directives within the various @code{<Feed>} sections. Since
300 @command{ffserver} will not launch any @command{ffmpeg} instances, you
301 will have to launch them manually.
304 Enable debug mode. This option increases log verbosity, and directs
305 log messages to stdout. When specified, the @option{CustomLog} option
309 @chapter Configuration file syntax
311 @command{ffserver} reads a configuration file containing global
312 options and settings for each stream and feed.
314 The configuration file consists of global options and dedicated
315 sections, which must be introduced by "<@var{SECTION_NAME}
316 @var{ARGS}>" on a separate line and must be terminated by a line in
317 the form "</@var{SECTION_NAME}>". @var{ARGS} is optional.
319 Currently the following sections are recognized: @samp{Feed},
320 @samp{Stream}, @samp{Redirect}.
322 A line starting with @code{#} is ignored and treated as a comment.
324 Name of options and sections are case-insensitive.
327 An ACL (Access Control List) specifies the address which are allowed
328 to access a given stream, or to write a given feed.
330 It accepts the following forms
333 Allow/deny access to @var{address}.
340 Allow/deny access to ranges of addresses from @var{first_address} to
343 ACL ALLOW <first_address> <last_address>
344 ACL DENY <first_address> <last_address>
348 You can repeat the ACL allow/deny as often as you like. It is on a per
349 stream basis. The first match defines the action. If there are no matches,
350 then the default is the inverse of the last ACL statement.
352 Thus 'ACL allow localhost' only allows access from localhost.
353 'ACL deny 1.0.0.0 1.255.255.255' would deny the whole of network 1 and
354 allow everybody else.
356 @section Global options
358 @item HTTPPort @var{port_number}
359 @item Port @var{port_number}
360 @item RTSPPort @var{port_number}
362 @var{HTTPPort} sets the HTTP server listening TCP port number,
363 @var{RTSPPort} sets the RTSP server listening TCP port number.
365 @var{Port} is the equivalent of @var{HTTPPort} and is deprecated.
367 You must select a different port from your standard HTTP web server if
368 it is running on the same computer.
370 If not specified, no corresponding server will be created.
372 @item HTTPBindAddress @var{ip_address}
373 @item BindAddress @var{ip_address}
374 @item RTSPBindAddress @var{ip_address}
375 Set address on which the HTTP/RTSP server is bound. Only useful if you
376 have several network interfaces.
378 @var{BindAddress} is the equivalent of @var{HTTPBindAddress} and is
381 @item MaxHTTPConnections @var{n}
382 Set number of simultaneous HTTP connections that can be handled. It
383 has to be defined @emph{before} the @option{MaxClients} parameter,
384 since it defines the @option{MaxClients} maximum limit.
386 Default value is 2000.
388 @item MaxClients @var{n}
389 Set number of simultaneous requests that can be handled. Since
390 @command{ffserver} is very fast, it is more likely that you will want
391 to leave this high and use @option{MaxBandwidth}.
395 @item MaxBandwidth @var{kbps}
396 Set the maximum amount of kbit/sec that you are prepared to consume
397 when streaming to clients.
399 Default value is 1000.
401 @item CustomLog @var{filename}
402 Set access log file (uses standard Apache log file format). '-' is the
405 If not specified @command{ffserver} will produce no log.
407 In case the commandline option @option{-d} is specified this option is
408 ignored, and the log is written to standard output.
411 Set no-daemon mode. This option is currently ignored since now
412 @command{ffserver} will always work in no-daemon mode, and is
417 Control whether default codec options are used for the all streams or not.
418 Each stream may overwrite this setting for its own. Default is @var{UseDefaults}.
419 The last occurrence overrides the previous if multiple definitions exist.
422 @section Feed section
424 A Feed section defines a feed provided to @command{ffserver}.
426 Each live feed contains one video and/or audio sequence coming from an
427 @command{ffmpeg} encoder or another @command{ffserver}. This sequence
428 may be encoded simultaneously with several codecs at several
431 A feed instance specification is introduced by a line in the form:
436 where @var{FEED_FILENAME} specifies the unique name of the FFM stream.
438 The following options are recognized within a Feed section.
441 @item File @var{filename}
442 @item ReadOnlyFile @var{filename}
443 Set the path where the feed file is stored on disk.
445 If not specified, the @file{/tmp/FEED.ffm} is assumed, where
446 @var{FEED} is the feed name.
448 If @option{ReadOnlyFile} is used the file is marked as read-only and
449 it will not be deleted or updated.
452 Truncate the feed file, rather than appending to it. By default
453 @command{ffserver} will append data to the file, until the maximum
454 file size value is reached (see @option{FileMaxSize} option).
456 @item FileMaxSize @var{size}
457 Set maximum size of the feed file in bytes. 0 means unlimited. The
458 postfixes @code{K} (2^10), @code{M} (2^20), and @code{G} (2^30) are
463 @item Launch @var{args}
464 Launch an @command{ffmpeg} command when creating @command{ffserver}.
466 @var{args} must be a sequence of arguments to be provided to an
467 @command{ffmpeg} instance. The first provided argument is ignored, and
468 it is replaced by a path with the same dirname of the @command{ffserver}
469 instance, followed by the remaining argument and terminated with a
470 path corresponding to the feed.
472 When the launched process exits, @command{ffserver} will launch
473 another program instance.
475 In case you need a more complex @command{ffmpeg} configuration,
476 e.g. if you need to generate multiple FFM feeds with a single
477 @command{ffmpeg} instance, you should launch @command{ffmpeg} by hand.
479 This option is ignored in case the commandline option @option{-n} is
483 Specify the list of IP address which are allowed or denied to write
484 the feed. Multiple ACL options can be specified.
487 @section Stream section
489 A Stream section defines a stream provided by @command{ffserver}, and
490 identified by a single name.
492 The stream is sent when answering a request containing the stream
495 A stream section must be introduced by the line:
500 where @var{STREAM_NAME} specifies the unique name of the stream.
502 The following options are recognized within a Stream section.
504 Encoding options are marked with the @emph{encoding} tag, and they are
505 used to set the encoding parameters, and are mapped to libavcodec
506 encoding options. Not all encoding options are supported, in
507 particular it is not possible to set encoder private options. In order
508 to override the encoding options specified by @command{ffserver}, you
509 can use the @command{ffmpeg} @option{override_ffserver} commandline
512 Only one of the @option{Feed} and @option{File} options should be set.
515 @item Feed @var{feed_name}
516 Set the input feed. @var{feed_name} must correspond to an existing
517 feed defined in a @code{Feed} section.
519 When this option is set, encoding options are used to setup the
520 encoding operated by the remote @command{ffmpeg} process.
522 @item File @var{filename}
523 Set the filename of the pre-recorded input file to stream.
525 When this option is set, encoding options are ignored and the input
526 file content is re-streamed as is.
528 @item Format @var{format_name}
529 Set the format of the output stream.
531 Must be the name of a format recognized by FFmpeg. If set to
532 @samp{status}, it is treated as a status stream.
534 @item InputFormat @var{format_name}
535 Set input format. If not specified, it is automatically guessed.
537 @item Preroll @var{n}
538 Set this to the number of seconds backwards in time to start. Note that
539 most players will buffer 5-10 seconds of video, and also you need to allow
540 for a keyframe to appear in the data stream.
545 Do not send stream until it gets the first key frame. By default
546 @command{ffserver} will send data immediately.
548 @item MaxTime @var{n}
549 Set the number of seconds to run. This value set the maximum duration
550 of the stream a client will be able to receive.
552 A value of 0 means that no limit is set on the stream duration.
555 Set ACL for the stream.
557 @item DynamicACL @var{spec}
559 @item RTSPOption @var{option}
561 @item MulticastAddress @var{address}
563 @item MulticastPort @var{port}
565 @item MulticastTTL @var{integer}
569 @item FaviconURL @var{url}
570 Set favicon (favourite icon) for the server status page. It is ignored
573 @item Author @var{value}
574 @item Comment @var{value}
575 @item Copyright @var{value}
576 @item Title @var{value}
577 Set metadata corresponding to the option. All these options are
578 deprecated in favor of @option{Metadata}.
580 @item Metadata @var{key} @var{value}
581 Set metadata value on the output stream.
585 Control whether default codec options are used for the stream or not.
586 Default is @var{UseDefaults} unless disabled globally.
590 Suppress audio/video.
592 @item AudioCodec @var{codec_name} (@emph{encoding,audio})
595 @item AudioBitRate @var{rate} (@emph{encoding,audio})
596 Set bitrate for the audio stream in kbits per second.
598 @item AudioChannels @var{n} (@emph{encoding,audio})
599 Set number of audio channels.
601 @item AudioSampleRate @var{n} (@emph{encoding,audio})
602 Set sampling frequency for audio. When using low bitrates, you should
603 lower this frequency to 22050 or 11025. The supported frequencies
604 depend on the selected audio codec.
606 @item AVOptionAudio [@var{codec}:]@var{option} @var{value} (@emph{encoding,audio})
607 Set generic or private option for audio stream.
608 Private option must be prefixed with codec name or codec must be defined before.
610 @item AVPresetAudio @var{preset} (@emph{encoding,audio})
611 Set preset for audio stream.
613 @item VideoCodec @var{codec_name} (@emph{encoding,video})
616 @item VideoBitRate @var{n} (@emph{encoding,video})
617 Set bitrate for the video stream in kbits per second.
619 @item VideoBitRateRange @var{range} (@emph{encoding,video})
620 Set video bitrate range.
622 A range must be specified in the form @var{minrate}-@var{maxrate}, and
623 specifies the @option{minrate} and @option{maxrate} encoding options
624 expressed in kbits per second.
626 @item VideoBitRateRangeTolerance @var{n} (@emph{encoding,video})
627 Set video bitrate tolerance in kbits per second.
629 @item PixelFormat @var{pixel_format} (@emph{encoding,video})
630 Set video pixel format.
632 @item Debug @var{integer} (@emph{encoding,video})
633 Set video @option{debug} encoding option.
635 @item Strict @var{integer} (@emph{encoding,video})
636 Set video @option{strict} encoding option.
638 @item VideoBufferSize @var{n} (@emph{encoding,video})
639 Set ratecontrol buffer size, expressed in KB.
641 @item VideoFrameRate @var{n} (@emph{encoding,video})
642 Set number of video frames per second.
644 @item VideoSize (@emph{encoding,video})
645 Set size of the video frame, must be an abbreviation or in the form
646 @var{W}x@var{H}. See @ref{video size syntax,,the Video size section
647 in the ffmpeg-utils(1) manual,ffmpeg-utils}.
649 Default value is @code{160x128}.
651 @item VideoIntraOnly (@emph{encoding,video})
652 Transmit only intra frames (useful for low bitrates, but kills frame rate).
654 @item VideoGopSize @var{n} (@emph{encoding,video})
655 If non-intra only, an intra frame is transmitted every VideoGopSize
656 frames. Video synchronization can only begin at an intra frame.
658 @item VideoTag @var{tag} (@emph{encoding,video})
661 @item VideoHighQuality (@emph{encoding,video})
662 @item Video4MotionVector (@emph{encoding,video})
664 @item BitExact (@emph{encoding,video})
665 Set bitexact encoding flag.
667 @item IdctSimple (@emph{encoding,video})
668 Set simple IDCT algorithm.
670 @item Qscale @var{n} (@emph{encoding,video})
671 Enable constant quality encoding, and set video qscale (quantization
672 scale) value, expressed in @var{n} QP units.
674 @item VideoQMin @var{n} (@emph{encoding,video})
675 @item VideoQMax @var{n} (@emph{encoding,video})
678 @item VideoQDiff @var{integer} (@emph{encoding,video})
679 Set video @option{qdiff} encoding option.
681 @item LumiMask @var{float} (@emph{encoding,video})
682 @item DarkMask @var{float} (@emph{encoding,video})
683 Set @option{lumi_mask}/@option{dark_mask} encoding options.
685 @item AVOptionVideo [@var{codec}:]@var{option} @var{value} (@emph{encoding,video})
686 Set generic or private option for video stream.
687 Private option must be prefixed with codec name or codec must be defined before.
689 @item AVPresetVideo @var{preset} (@emph{encoding,video})
690 Set preset for video stream.
692 @var{preset} must be the path of a preset file.
695 @subsection Server status stream
697 A server status stream is a special stream which is used to show
698 statistics about the @command{ffserver} operations.
700 It must be specified setting the option @option{Format} to
703 @section Redirect section
705 A redirect section specifies where to redirect the requested URL to
708 A redirect section must be introduced by the line:
713 where @var{NAME} is the name of the page which should be redirected.
715 It only accepts the option @option{URL}, which specify the redirection
718 @chapter Stream examples
785 AudioSampleRate 44100
795 Metadata title "Stream title"
798 AudioSampleRate 44100
804 Real with audio only at 32 kbits
815 Real with audio and video at 64 kbits
828 For stream coming from a file: you only need to set the input filename
829 and optionally a new format.
833 File "/usr/local/httpd/htdocs/tlive.rm"
840 File "/usr/local/httpd/htdocs/test.asf"
843 Metadata copyright "Super MegaCorp"
844 Metadata title "Test stream from disk"
845 Metadata comment "Test comment"
857 @ifset config-avcodec
859 @include bitstream_filters.texi
861 @ifset config-avformat
862 @include formats.texi
863 @include protocols.texi
865 @ifset config-avdevice
866 @include devices.texi
868 @ifset config-swresample
869 @include resampler.texi
871 @ifset config-swscale
874 @ifset config-avfilter
875 @include filters.texi
883 @url{ffserver.html,ffserver},
885 @ifset config-not-all
886 @url{ffserver-all.html,ffserver-all},
888 the @file{doc/ffserver.conf} example,
889 @url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe},
890 @url{ffmpeg-utils.html,ffmpeg-utils},
891 @url{ffmpeg-scaler.html,ffmpeg-scaler},
892 @url{ffmpeg-resampler.html,ffmpeg-resampler},
893 @url{ffmpeg-codecs.html,ffmpeg-codecs},
894 @url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters},
895 @url{ffmpeg-formats.html,ffmpeg-formats},
896 @url{ffmpeg-devices.html,ffmpeg-devices},
897 @url{ffmpeg-protocols.html,ffmpeg-protocols},
898 @url{ffmpeg-filters.html,ffmpeg-filters}
905 @ifset config-not-all
908 the @file{doc/ffserver.conf} example, ffmpeg(1), ffplay(1), ffprobe(1),
909 ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
910 ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),
911 ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1)
914 @include authors.texi
918 @setfilename ffserver
919 @settitle ffserver video server