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

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

LGTM from readability perspective. Nice catch on the command missing slash.

On Mon, Mar 11, 2024 at 11:15 AM Stefano Sabatini <stefasab@gmail.com>
wrote:

> ---
>  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.
> +
> +@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 queue_size @var{size}
> +Specify size of the queue as a number of packets. Default value is
> +@code{60}.
>
> -@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 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
> +@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 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_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).
>
> -@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).
>
> -@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}.
>
> -@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.
> +@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
> -
> -@itemize
> +@subsection Example
>
> -@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
>
> -@end itemize
> -
>  @section flv
>
>  Adobe Flash Video Format muxer.
> --
> 2.34.1
>
> _______________________________________________
> ffmpeg-devel mailing list
> ffmpeg-devel@ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".
>

On date Monday 2024-03-11 11:32:29 -0500, Marth64 wrote:
> LGTM from readability perspective. Nice catch on the command missing slash.

Thanks, applied.