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 allow 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
124 ffmpeg 1 -----| feed 1 |-----| stream 1 |
125 \ |_________|\ |__________|
132 \ _________ __________
134 \| feed 2 |-----| stream 3 |
135 |_________| |__________|
139 ffmpeg 2 -----| feed 3 |-----| stream 4 |
140 |_________| |__________|
144 | file 1 |-----| stream 5 |
145 |_________| |__________|
149 @section FFM, FFM2 formats
151 FFM and FFM2 are formats used by ffserver. They allow storing a wide variety of
152 video and audio streams and encoding options, and can store a moving time segment
153 of an infinite movie or a whole movie.
155 FFM is version specific, and there is limited compatibility of FFM files
156 generated by one version of ffmpeg/ffserver and another version of
157 ffmpeg/ffserver. It may work but it is not guaranteed to work.
159 FFM2 is extensible while maintaining compatibility and should work between
160 differing versions of tools. FFM2 is the default.
162 @section Status stream
164 @command{ffserver} supports an HTTP interface which exposes the
165 current status of the server.
167 Simply point your browser to the address of the special status stream
168 specified in the configuration file.
170 For example if you have:
175 # Only allow local people to get the status
177 ACL allow 192.168.0.0 192.168.255.255
181 then the server will post a page with the status information when
182 the special stream @file{status.html} is requested.
184 @section How do I make it work?
186 As a simple test, just run the following two command lines where INPUTFILE
187 is some file which you can decode with ffmpeg:
190 ffserver -f doc/ffserver.conf &
191 ffmpeg -i INPUTFILE http://localhost:8090/feed1.ffm
194 At this point you should be able to go to your Windows machine and fire up
195 Windows Media Player (WMP). Go to Open URL and enter
198 http://<linuxbox>:8090/test.asf
201 You should (after a short delay) see video and hear audio.
203 WARNING: trying to stream test1.mpg doesn't work with WMP as it tries to
204 transfer the entire file before starting to play.
205 The same is true of AVI files.
207 You should edit the @file{ffserver.conf} file to suit your needs (in
208 terms of frame rates etc). Then install @command{ffserver} and
209 @command{ffmpeg}, write a script to start them up, and off you go.
211 @section What else can it do?
213 You can replay video from .ffm files that was recorded earlier.
214 However, there are a number of caveats, including the fact that the
215 ffserver parameters must match the original parameters used to record the
216 file. If they do not, then ffserver deletes the file before recording into it.
217 (Now that I write this, it seems broken).
219 You can fiddle with many of the codec choices and encoding parameters, and
220 there are a bunch more parameters that you cannot control. Post a message
221 to the mailing list if there are some 'must have' parameters. Look in
222 ffserver.conf for a list of the currently available controls.
224 It will automatically generate the ASX or RAM files that are often used
225 in browsers. These files are actually redirections to the underlying ASF
226 or RM file. The reason for this is that the browser often fetches the
227 entire file before starting up the external viewer. The redirection files
228 are very small and can be transferred quickly. [The stream itself is
229 often 'infinite' and thus the browser tries to download it and never
234 * When you connect to a live stream, most players (WMP, RA, etc) want to
235 buffer a certain number of seconds of material so that they can display the
236 signal continuously. However, ffserver (by default) starts sending data
237 in realtime. This means that there is a pause of a few seconds while the
238 buffering is being done by the player. The good news is that this can be
239 cured by adding a '?buffer=5' to the end of the URL. This means that the
240 stream should start 5 seconds in the past -- and so the first 5 seconds
241 of the stream are sent as fast as the network will allow. It will then
242 slow down to real time. This noticeably improves the startup experience.
244 You can also add a 'Preroll 15' statement into the ffserver.conf that will
245 add the 15 second prebuffering on all requests that do not otherwise
246 specify a time. In addition, ffserver will skip frames until a key_frame
247 is found. This further reduces the startup delay by not transferring data
248 that will be discarded.
250 @section Why does the ?buffer / Preroll stop working after a time?
252 It turns out that (on my machine at least) the number of frames successfully
253 grabbed is marginally less than the number that ought to be grabbed. This
254 means that the timestamp in the encoded data stream gets behind realtime.
255 This means that if you say 'Preroll 10', then when the stream gets 10
256 or more seconds behind, there is no Preroll left.
258 Fixing this requires a change in the internals of how timestamps are
261 @section Does the @code{?date=} stuff work.
263 Yes (subject to the limitation outlined above). Also note that whenever you
264 start ffserver, it deletes the ffm file (if any parameters have changed),
265 thus wiping out what you had recorded before.
267 The format of the @code{?date=xxxxxx} is fairly flexible. You should use one
268 of the following formats (the 'T' is literal):
271 * YYYY-MM-DDTHH:MM:SS (localtime)
272 * YYYY-MM-DDTHH:MM:SSZ (UTC)
275 You can omit the YYYY-MM-DD, and then it refers to the current day. However
276 note that @samp{?date=16:00:00} refers to 16:00 on the current day -- this
277 may be in the future and so is unlikely to be useful.
279 You use this by adding the ?date= to the end of the URL for the stream.
280 For example: @samp{http://localhost:8080/test.asf?date=2002-07-26T23:05:00}.
286 @include fftools-common-opts.texi
288 @section Main options
291 @item -f @var{configfile}
292 Read configuration file @file{configfile}. If not specified it will
293 read by default from @file{/etc/ffserver.conf}.
296 Enable no-launch mode. This option disables all the @code{Launch}
297 directives within the various @code{<Feed>} sections. Since
298 @command{ffserver} will not launch any @command{ffmpeg} instances, you
299 will have to launch them manually.
302 Enable debug mode. This option increases log verbosity, and directs
303 log messages to stdout. When specified, the @option{CustomLog} option
307 @chapter Configuration file syntax
309 @command{ffserver} reads a configuration file containing global
310 options and settings for each stream and feed.
312 The configuration file consists of global options and dedicated
313 sections, which must be introduced by "<@var{SECTION_NAME}
314 @var{ARGS}>" on a separate line and must be terminated by a line in
315 the form "</@var{SECTION_NAME}>". @var{ARGS} is optional.
317 Currently the following sections are recognized: @samp{Feed},
318 @samp{Stream}, @samp{Redirect}.
320 A line starting with @code{#} is ignored and treated as a comment.
322 Name of options and sections are case-insensitive.
325 An ACL (Access Control List) specifies the address which are allowed
326 to access a given stream, or to write a given feed.
328 It accepts the folling forms
331 Allow/deny access to @var{address}.
338 Allow/deny access to ranges of addresses from @var{first_address} to
341 ACL ALLOW <first_address> <last_address>
342 ACL DENY <first_address> <last_address>
346 You can repeat the ACL allow/deny as often as you like. It is on a per
347 stream basis. The first match defines the action. If there are no matches,
348 then the default is the inverse of the last ACL statement.
350 Thus 'ACL allow localhost' only allows access from localhost.
351 'ACL deny 1.0.0.0 1.255.255.255' would deny the whole of network 1 and
352 allow everybody else.
354 @section Global options
356 @item HTTPPort @var{port_number}
357 @item Port @var{port_number}
358 @item RTSPPort @var{port_number}
360 @var{HTTPPort} sets the HTTP server listening TCP port number,
361 @var{RTSPPort} sets the RTSP server listening TCP port number.
363 @var{Port} is the equivalent of @var{HTTPPort} and is deprecated.
365 You must select a different port from your standard HTTP web server if
366 it is running on the same computer.
368 If not specified, no corresponding server will be created.
370 @item HTTPBindAddress @var{ip_address}
371 @item BindAddress @var{ip_address}
372 @item RTSPBindAddress @var{ip_address}
373 Set address on which the HTTP/RTSP server is bound. Only useful if you
374 have several network interfaces.
376 @var{BindAddress} is the equivalent of @var{HTTPBindAddress} and is
379 @item MaxHTTPConnections @var{n}
380 Set number of simultaneous HTTP connections that can be handled. It
381 has to be defined @emph{before} the @option{MaxClients} parameter,
382 since it defines the @option{MaxClients} maximum limit.
384 Default value is 2000.
386 @item MaxClients @var{n}
387 Set number of simultaneous requests that can be handled. Since
388 @command{ffserver} is very fast, it is more likely that you will want
389 to leave this high and use @option{MaxBandwidth}.
393 @item MaxBandwidth @var{kbps}
394 Set the maximum amount of kbit/sec that you are prepared to consume
395 when streaming to clients.
397 Default value is 1000.
399 @item CustomLog @var{filename}
400 Set access log file (uses standard Apache log file format). '-' is the
403 If not specified @command{ffserver} will produce no log.
405 In case the commandline option @option{-d} is specified this option is
406 ignored, and the log is written to standard output.
409 Set no-daemon mode. This option is currently ignored since now
410 @command{ffserver} will always work in no-daemon mode, and is
415 Control whether default codec options are used for the all streams or not.
416 Each stream may overwrite this setting for its own. Default is @var{UseDefaults}.
417 The lastest occurrence overrides previous if multiple definitions.
420 @section Feed section
422 A Feed section defines a feed provided to @command{ffserver}.
424 Each live feed contains one video and/or audio sequence coming from an
425 @command{ffmpeg} encoder or another @command{ffserver}. This sequence
426 may be encoded simultaneously with several codecs at several
429 A feed instance specification is introduced by a line in the form:
434 where @var{FEED_FILENAME} specifies the unique name of the FFM stream.
436 The following options are recognized within a Feed section.
439 @item File @var{filename}
440 @item ReadOnlyFile @var{filename}
441 Set the path where the feed file is stored on disk.
443 If not specified, the @file{/tmp/FEED.ffm} is assumed, where
444 @var{FEED} is the feed name.
446 If @option{ReadOnlyFile} is used the file is marked as read-only and
447 it will not be deleted or updated.
450 Truncate the feed file, rather than appending to it. By default
451 @command{ffserver} will append data to the file, until the maximum
452 file size value is reached (see @option{FileMaxSize} option).
454 @item FileMaxSize @var{size}
455 Set maximum size of the feed file in bytes. 0 means unlimited. The
456 postfixes @code{K} (2^10), @code{M} (2^20), and @code{G} (2^30) are
461 @item Launch @var{args}
462 Launch an @command{ffmpeg} command when creating @command{ffserver}.
464 @var{args} must be a sequence of arguments to be provided to an
465 @command{ffmpeg} instance. The first provided argument is ignored, and
466 it is replaced by a path with the same dirname of the @command{ffserver}
467 instance, followed by the remaining argument and terminated with a
468 path corresponding to the feed.
470 When the launched process exits, @command{ffserver} will launch
471 another program instance.
473 In case you need a more complex @command{ffmpeg} configuration,
474 e.g. if you need to generate multiple FFM feeds with a single
475 @command{ffmpeg} instance, you should launch @command{ffmpeg} by hand.
477 This option is ignored in case the commandline option @option{-n} is
481 Specify the list of IP address which are allowed or denied to write
482 the feed. Multiple ACL options can be specified.
485 @section Stream section
487 A Stream section defines a stream provided by @command{ffserver}, and
488 identified by a single name.
490 The stream is sent when answering a request containing the stream
493 A stream section must be introduced by the line:
498 where @var{STREAM_NAME} specifies the unique name of the stream.
500 The following options are recognized within a Stream section.
502 Encoding options are marked with the @emph{encoding} tag, and they are
503 used to set the encoding parameters, and are mapped to libavcodec
504 encoding options. Not all encoding options are supported, in
505 particular it is not possible to set encoder private options. In order
506 to override the encoding options specified by @command{ffserver}, you
507 can use the @command{ffmpeg} @option{override_ffserver} commandline
510 Only one of the @option{Feed} and @option{File} options should be set.
513 @item Feed @var{feed_name}
514 Set the input feed. @var{feed_name} must correspond to an existing
515 feed defined in a @code{Feed} section.
517 When this option is set, encoding options are used to setup the
518 encoding operated by the remote @command{ffmpeg} process.
520 @item File @var{filename}
521 Set the filename of the pre-recorded input file to stream.
523 When this option is set, encoding options are ignored and the input
524 file content is re-streamed as is.
526 @item Format @var{format_name}
527 Set the format of the output stream.
529 Must be the name of a format recognized by FFmpeg. If set to
530 @samp{status}, it is treated as a status stream.
532 @item InputFormat @var{format_name}
533 Set input format. If not specified, it is automatically guessed.
535 @item Preroll @var{n}
536 Set this to the number of seconds backwards in time to start. Note that
537 most players will buffer 5-10 seconds of video, and also you need to allow
538 for a keyframe to appear in the data stream.
543 Do not send stream until it gets the first key frame. By default
544 @command{ffserver} will send data immediately.
546 @item MaxTime @var{n}
547 Set the number of seconds to run. This value set the maximum duration
548 of the stream a client will be able to receive.
550 A value of 0 means that no limit is set on the stream duration.
553 Set ACL for the stream.
555 @item DynamicACL @var{spec}
557 @item RTSPOption @var{option}
559 @item MulticastAddress @var{address}
561 @item MulticastPort @var{port}
563 @item MulticastTTL @var{integer}
567 @item FaviconURL @var{url}
568 Set favicon (favourite icon) for the server status page. It is ignored
571 @item Author @var{value}
572 @item Comment @var{value}
573 @item Copyright @var{value}
574 @item Title @var{value}
575 Set metadata corresponding to the option. All these options are
576 deprecated in favor of @option{Metadata}.
578 @item Metadata @var{key} @var{value}
579 Set metadata value on the output stream.
583 Control whether default codec options are used for the stream or not.
584 Default is @var{UseDefaults} unless disabled globally.
588 Suppress audio/video.
590 @item AudioCodec @var{codec_name} (@emph{encoding,audio})
593 @item AudioBitRate @var{rate} (@emph{encoding,audio})
594 Set bitrate for the audio stream in kbits per second.
596 @item AudioChannels @var{n} (@emph{encoding,audio})
597 Set number of audio channels.
599 @item AudioSampleRate @var{n} (@emph{encoding,audio})
600 Set sampling frequency for audio. When using low bitrates, you should
601 lower this frequency to 22050 or 11025. The supported frequencies
602 depend on the selected audio codec.
604 @item AVOptionAudio [@var{codec}:]@var{option} @var{value} (@emph{encoding,audio})
605 Set generic or private option for audio stream.
606 Private option must be prefixed with codec name or codec must be defined before.
608 @item AVPresetAudio @var{preset} (@emph{encoding,audio})
609 Set preset for audio stream.
611 @item VideoCodec @var{codec_name} (@emph{encoding,video})
614 @item VideoBitRate @var{n} (@emph{encoding,video})
615 Set bitrate for the video stream in kbits per second.
617 @item VideoBitRateRange @var{range} (@emph{encoding,video})
618 Set video bitrate range.
620 A range must be specified in the form @var{minrate}-@var{maxrate}, and
621 specifies the @option{minrate} and @option{maxrate} encoding options
622 expressed in kbits per second.
624 @item VideoBitRateRangeTolerance @var{n} (@emph{encoding,video})
625 Set video bitrate tolerance in kbits per second.
627 @item PixelFormat @var{pixel_format} (@emph{encoding,video})
628 Set video pixel format.
630 @item Debug @var{integer} (@emph{encoding,video})
631 Set video @option{debug} encoding option.
633 @item Strict @var{integer} (@emph{encoding,video})
634 Set video @option{strict} encoding option.
636 @item VideoBufferSize @var{n} (@emph{encoding,video})
637 Set ratecontrol buffer size, expressed in KB.
639 @item VideoFrameRate @var{n} (@emph{encoding,video})
640 Set number of video frames per second.
642 @item VideoSize (@emph{encoding,video})
643 Set size of the video frame, must be an abbreviation or in the form
644 @var{W}x@var{H}. See @ref{video size syntax,,the Video size section
645 in the ffmpeg-utils(1) manual,ffmpeg-utils}.
647 Default value is @code{160x128}.
649 @item VideoIntraOnly (@emph{encoding,video})
650 Transmit only intra frames (useful for low bitrates, but kills frame rate).
652 @item VideoGopSize @var{n} (@emph{encoding,video})
653 If non-intra only, an intra frame is transmitted every VideoGopSize
654 frames. Video synchronization can only begin at an intra frame.
656 @item VideoTag @var{tag} (@emph{encoding,video})
659 @item VideoHighQuality (@emph{encoding,video})
660 @item Video4MotionVector (@emph{encoding,video})
662 @item BitExact (@emph{encoding,video})
663 Set bitexact encoding flag.
665 @item IdctSimple (@emph{encoding,video})
666 Set simple IDCT algorithm.
668 @item Qscale @var{n} (@emph{encoding,video})
669 Enable constant quality encoding, and set video qscale (quantization
670 scale) value, expressed in @var{n} QP units.
672 @item VideoQMin @var{n} (@emph{encoding,video})
673 @item VideoQMax @var{n} (@emph{encoding,video})
676 @item VideoQDiff @var{integer} (@emph{encoding,video})
677 Set video @option{qdiff} encoding option.
679 @item LumiMask @var{float} (@emph{encoding,video})
680 @item DarkMask @var{float} (@emph{encoding,video})
681 Set @option{lumi_mask}/@option{dark_mask} encoding options.
683 @item AVOptionVideo [@var{codec}:]@var{option} @var{value} (@emph{encoding,video})
684 Set generic or private option for video stream.
685 Private option must be prefixed with codec name or codec must be defined before.
687 @item AVPresetVideo @var{preset} (@emph{encoding,video})
688 Set preset for video stream.
690 @var{preset} must be the path of a preset file.
693 @subsection Server status stream
695 A server status stream is a special stream which is used to show
696 statistics about the @command{ffserver} operations.
698 It must be specified setting the option @option{Format} to
701 @section Redirect section
703 A redirect section specifies where to redirect the requested URL to
706 A redirect section must be introduced by the line:
711 where @var{NAME} is the name of the page which should be redirected.
713 It only accepts the option @option{URL}, which specify the redirection
716 @chapter Stream examples
783 AudioSampleRate 44100
793 Metadata title "Stream title"
796 AudioSampleRate 44100
802 Real with audio only at 32 kbits
813 Real with audio and video at 64 kbits
826 For stream coming from a file: you only need to set the input filename
827 and optionally a new format.
831 File "/usr/local/httpd/htdocs/tlive.rm"
838 File "/usr/local/httpd/htdocs/test.asf"
841 Metadata copyright "Super MegaCorp"
842 Metadata title "Test stream from disk"
843 Metadata comment "Test comment"
855 @ifset config-avcodec
857 @include bitstream_filters.texi
859 @ifset config-avformat
860 @include formats.texi
861 @include protocols.texi
863 @ifset config-avdevice
864 @include devices.texi
866 @ifset config-swresample
867 @include resampler.texi
869 @ifset config-swscale
872 @ifset config-avfilter
873 @include filters.texi
881 @url{ffserver.html,ffserver},
883 @ifset config-not-all
884 @url{ffserver-all.html,ffserver-all},
886 the @file{doc/ffserver.conf} example,
887 @url{ffmpeg.html,ffmpeg}, @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe},
888 @url{ffmpeg-utils.html,ffmpeg-utils},
889 @url{ffmpeg-scaler.html,ffmpeg-scaler},
890 @url{ffmpeg-resampler.html,ffmpeg-resampler},
891 @url{ffmpeg-codecs.html,ffmpeg-codecs},
892 @url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters},
893 @url{ffmpeg-formats.html,ffmpeg-formats},
894 @url{ffmpeg-devices.html,ffmpeg-devices},
895 @url{ffmpeg-protocols.html,ffmpeg-protocols},
896 @url{ffmpeg-filters.html,ffmpeg-filters}
903 @ifset config-not-all
906 the @file{doc/ffserver.conf} example, ffmpeg(1), ffplay(1), ffprobe(1),
907 ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
908 ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),
909 ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1)
912 @include authors.texi
916 @setfilename ffserver
917 @settitle ffserver video server