diff --git a/doc/muxers.texi b/doc/muxers.texi index 2104cc4a95..7f05dfcb69 100644 --- a/doc/muxers.texi +++ b/doc/muxers.texi @@ -1421,104 +1421,115 @@ ffmpeg -i INPUT -s:v 720x480 -pix_fmt yuv411p -r 29.97 -ac 2 -ar 48000 -y out.dv @anchor{fifo} @section fifo +FIFO (First-In First-Out) muxer. -The fifo pseudo-muxer allows the separation of encoding and muxing by using -first-in-first-out queue and running the actual muxer in a separate thread. This -is especially useful in combination with the @ref{tee} muxer and can be used to -send data to several destinations with different reliability/writing speed/latency. +The @samp{fifo} pseudo-muxer allows the separation of encoding and +muxing by using a first-in-first-out queue and running the actual muxer +in a separate thread. -API users should be aware that callback functions (interrupt_callback, -io_open and io_close) used within its AVFormatContext must be thread-safe. +This is especially useful in combination with +the @ref{tee} muxer and can be used to send data to several +destinations with different reliability/writing speed/latency. -The behavior of the fifo muxer if the queue fills up or if the output fails is -selectable, +The target muxer is either selected from the output name or specified +through the @option{fifo_format} option. +The behavior of the @samp{fifo} muxer if the queue fills up or if the +output fails (e.g. if a packet cannot be written to the output) is +selectable: @itemize @bullet +@item +Output can be transparently restarted with configurable delay between +retries based on real time or time of the processed stream. @item -output can be transparently restarted with configurable delay between retries -based on real time or time of the processed stream. - -@item -encoding can be blocked during temporary failure, or continue transparently -dropping packets in case fifo queue fills up. - +Encoding can be blocked during temporary failure, or continue transparently +dropping packets in case the FIFO queue fills up. @end itemize +API users should be aware that callback functions +(@code{interrupt_callback}, @code{io_open} and @code{io_close}) used +within its @code{AVFormatContext} must be thread-safe. + +@subsection Options @table @option -@item fifo_format +@item attempt_recovery @var{bool} +If failure occurs, attempt to recover the output. This is especially +useful when used with network output, since it makes it possible to +restart streaming transparently. By default this option is set to +@code{false}. + +@item drop_pkts_on_overflow @var{bool} +If set to @code{true}, in case the fifo queue fills up, packets will +be dropped rather than blocking the encoder. This makes it possible to +continue streaming without delaying the input, at the cost of omitting +part of the stream. By default this option is set to @code{false}, so in +such cases the encoder will be blocked until the muxer processes some +of the packets and none of them is lost. + +@item fifo_format @var{format_name} Specify the format name. Useful if it cannot be guessed from the output name suffix. -@item queue_size -Specify size of the queue (number of packets). Default value is 60. +@item format_opts @var{options} +Specify format options for the underlying muxer. Muxer options can be +specified as a list of @var{key}=@var{value} pairs separated by ':'. -@item format_opts -Specify format options for the underlying muxer. Muxer options can be specified -as a list of @var{key}=@var{value} pairs separated by ':'. +@item max_recovery_attempts @var{count} +Set maximum number of successive unsuccessful recovery attempts after +which the output fails permanently. By default this option is set to +@code{0} (unlimited). -@item drop_pkts_on_overflow @var{bool} -If set to 1 (true), in case the fifo queue fills up, packets will be dropped -rather than blocking the encoder. This makes it possible to continue streaming without -delaying the input, at the cost of omitting part of the stream. By default -this option is set to 0 (false), so in such cases the encoder will be blocked -until the muxer processes some of the packets and none of them is lost. - -@item attempt_recovery @var{bool} -If failure occurs, attempt to recover the output. This is especially useful -when used with network output, since it makes it possible to restart streaming transparently. -By default this option is set to 0 (false). - -@item max_recovery_attempts -Sets maximum number of successive unsuccessful recovery attempts after which -the output fails permanently. By default this option is set to 0 (unlimited). - -@item recovery_wait_time @var{duration} -Waiting time before the next recovery attempt after previous unsuccessful -recovery attempt. Default value is 5 seconds. - -@item recovery_wait_streamtime @var{bool} -If set to 0 (false), the real time is used when waiting for the recovery -attempt (i.e. the recovery will be attempted after at least -recovery_wait_time seconds). -If set to 1 (true), the time of the processed stream is taken into account -instead (i.e. the recovery will be attempted after at least @var{recovery_wait_time} -seconds of the stream is omitted). -By default, this option is set to 0 (false). +@item queue_size @var{size} +Specify size of the queue as a number of packets. Default value is +@code{60}. @item recover_any_error @var{bool} -If set to 1 (true), recovery will be attempted regardless of type of the error -causing the failure. By default this option is set to 0 (false) and in case of -certain (usually permanent) errors the recovery is not attempted even when -@var{attempt_recovery} is set to 1. +If set to @code{true}, recovery will be attempted regardless of type +of the error causing the failure. By default this option is set to +@code{false} and in case of certain (usually permanent) errors the +recovery is not attempted even when the @option{attempt_recovery} +option is set to @code{true}. + +@item recovery_wait_streamtime @var{bool} +If set to @code{false}, the real time is used when waiting for the +recovery attempt (i.e. the recovery will be attempted after the time +specified by the @option{recovery_wait_time} option). + +If set to @code{true}, the time of the processed stream is taken into +account instead (i.e. the recovery will be attempted after discarding +the packets corresponding to the @option{recovery_wait_time} option). + +By default this option is set to @code{false}. + +@item recovery_wait_time @var{duration} +Specify waiting time in seconds before the next recovery attempt after +previous unsuccessful recovery attempt. Default value is @code{5}. @item restart_with_keyframe @var{bool} Specify whether to wait for the keyframe after recovering from -queue overflow or failure. This option is set to 0 (false) by default. +queue overflow or failure. This option is set to @code{false} by default. @item timeshift @var{duration} -Buffer the specified amount of packets and delay writing the output. Note that -@var{queue_size} must be big enough to store the packets for timeshift. At the -end of the input the fifo buffer is flushed at realtime speed. - +Buffer the specified amount of packets and delay writing the +output. Note that the value of the @option{queue_size} option must be +big enough to store the packets for timeshift. At the end of the input +the fifo buffer is flushed at realtime speed. @end table -@subsection Examples +@subsection Example -@itemize - -@item -Stream something to rtmp server, continue processing the stream at real-time -rate even in case of temporary failure (network outage) and attempt to recover -streaming every second indefinitely. +Use @command{ffmpeg} to stream to an RTMP server, continue processing +the stream at real-time rate even in case of temporary failure +(network outage) and attempt to recover streaming every second +indefinitely: @example -ffmpeg -re -i ... -c:v libx264 -c:a aac -f fifo -fifo_format flv -map 0:v -map 0:a - -drop_pkts_on_overflow 1 -attempt_recovery 1 -recovery_wait_time 1 rtmp://example.com/live/stream_name +ffmpeg -re -i ... -c:v libx264 -c:a aac -f fifo -fifo_format flv \ + -drop_pkts_on_overflow 1 -attempt_recovery 1 -recovery_wait_time 1 \ + -map 0:v -map 0:a rtmp://example.com/live/stream_name @end example -@end itemize - @section flv Adobe Flash Video Format muxer.