[FFmpeg-devel] [PATCH 3/3] doc/muxers/fifo: review documentation

Mon Mar 11 18:14:43 EET 2024

---
 doc/muxers.texi | 138 ++++++++++++++++++++++++++----------------------
 1 file changed, 74 insertions(+), 64 deletions(-)

diff --git a/doc/muxers.texi b/doc/muxers.texi
index 2104cc4a95..34de187f5e 100644
--- a/doc/muxers.texi
+++ b/doc/muxers.texi
@@ -1421,104 +1421,114 @@ 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.
+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.
+
+ at subsection Options
 @table @option
 
- at item fifo_format
+ at 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
+ at code{false}.
+
+ at 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.
+
+ at item fifo_format @var{format_name}
 Specify the format name. Useful if it cannot be guessed from the
 output name suffix.
 
- at item queue_size
-Specify size of the queue (number of packets). Default value is 60.
+ at 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 ':'.
 
- at 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 ':'.
+ at 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
+ at code{0} (unlimited).
 
- at 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.
+ at item queue_size @var{size}
+Specify size of the queue as a number of packets. Default value is
+ at code{60}.
 
- at 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).
+ at item recover_any_error @var{bool}
+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
+ at 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}.
 
- at 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).
+ at 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).
 
- at item recovery_wait_time @var{duration}
-Waiting time before the next recovery attempt after previous unsuccessful
-recovery attempt. Default value is 5 seconds.
+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).
 
- at 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).
+By default this option is set to @code{false}.
 
- at 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
- at var{attempt_recovery} is set to 1.
+ at 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
- at 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
 
- at subsection Examples
-
- at itemize
+ at subsection Example
 
- at 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
+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
 @end example
 
- at end itemize
-
 @section flv
 
 Adobe Flash Video Format muxer.
-- 
2.34.1

