From patchwork Mon Mar 11 16:14:31 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefano Sabatini X-Patchwork-Id: 46958 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:dc95:b0:1a1:738b:6bc0 with SMTP id ky21csp1323146pzb; Mon, 11 Mar 2024 09:15:03 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCVahCHIBWDSiQtoiirA9U/H4tWNxVudjRFE9FAO6AqYhWbb614hf3FBUOQULVfGGN+5ZKb1S7ONUaPjV6QYWfOYtzECraGyiRibwA== X-Google-Smtp-Source: AGHT+IEFZoe+eVmAeYMWfn92drIElWJfaP1F4rv7ettrphzvi7xRQeeeejN0/sd0FNE65Ob1NV07 X-Received: by 2002:a17:907:118c:b0:a46:3ba4:ece4 with SMTP id uz12-20020a170907118c00b00a463ba4ece4mr58776ejb.69.1710173702973; Mon, 11 Mar 2024 09:15:02 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1710173702; cv=none; d=google.com; s=arc-20160816; b=aUazqIbfLqTCvT7z+r79uKw23MAFzGk/bfL8eLte7CfxQIjS6n3ClJw+HBo4QXkyuu I3WeFYCr4upBm0RkQyTG+bEChu6skKM0jn6XHbaAGjodlalKmu9FxJjKL/N++6k1OEQG cuGfQPz41B7XYg1EeMruV9Uu6Ppvzl24mACJDC66q3Bs8HAmA+oop0qNndvlmKRlHLCk 2/FXvKJ8kt6aNhzABaJ/ISL0AcOLW0LWdfy/Tcn40owq/UiQUPO5MnwLG6T8QVXz9P5o rugObIFY45vds5+4vohTAoXXnat/JG+zXsRTNEtYKZasnXy+Ngq+8MXknhD2JACObl/4 n5/Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature:delivered-to; bh=gjDck5GPbOpReyl1EG/qWvUcDR3LnY6zy8UlBQfvd0Q=; fh=QdWxt2OToL83TTnLQn0lGhLakV7i1QyAJdC8te7qN0E=; b=m9b/14FAtJOW87JPBd+51C/FVTyb27qhYEM081GxrvGRFs8Qgb6VfjPPMf8yqeFH3P QYAmftl8dcf48ZPXP1Eteb0B6ky3MaXsGmR846c3b9HOt1Dhj3CdZIM/VkANJQd4Hr+3 NoorFTx0uBl3rZiRKlua0zMUkynj5pARX65oGfmChFdEYU4i44XM849pEGk0bl4RgHsU CiweokGIGOQtFnJMmj9sTFcD5m3WtCBQihhYo4Ltfktn0IbhdxhIPaBh3Xu8hXwZUJA2 08UMl+Qxuh8oYmOoo719hZEn3KQRstzPHm3xeztb0frvWiudDHzhIWPx9rr7fpzNWwPo DOkw==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20230601 header.b=mhOXCFTk; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id kl14-20020a170907994e00b00a4627121f64si1074321ejc.798.2024.03.11.09.15.02; Mon, 11 Mar 2024 09:15:02 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20230601 header.b=mhOXCFTk; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 066E468D091; Mon, 11 Mar 2024 18:14:44 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-ej1-f53.google.com (mail-ej1-f53.google.com [209.85.218.53]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 3D54C68D097 for ; Mon, 11 Mar 2024 18:14:35 +0200 (EET) Received: by mail-ej1-f53.google.com with SMTP id a640c23a62f3a-a44d084bfe1so389526366b.1 for ; Mon, 11 Mar 2024 09:14:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1710173674; x=1710778474; darn=ffmpeg.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=S0VpZ/ATYuNmzZkkpsnol6uUHM7b1WIDqbeY39DtRrI=; b=mhOXCFTkO3BpkbU+X9itu5lLvtcPHgiOhzlLcEvXXtj30UnGuEYWbC7msKz+hM/rHu 0P8Xn9R7l5NA8JKdp1/7YgWO71Z0MHzjEYnvVbMPALi9TchYwezROoDuhS7Me1jDHOHw ZA+Bbzqs6JmdTiFsyjDV0/PmR75A5nyYt/MmP3T52s1og62A+ADqU3slazNRNjEtNAFy +eiO8ZcdzOE/qhIA/FfInKx3WAc8F1qDdkVDDU1vOV2C6KZzyiRIDmPbiu/oPKNGFLuv vqdsxko9YDYuopm6IqADFRrdIVkE7qrBBvfyEoP5wj6/9Bdl3OzL/fgwcZsvplxec14Q FVQg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1710173674; x=1710778474; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=S0VpZ/ATYuNmzZkkpsnol6uUHM7b1WIDqbeY39DtRrI=; b=bNoz9B+XR5t5pjWXCsOaCkVRa1s7sv3xB1xhY3mjSmO5ujaxhB3oEGiiTHpFaWO277 iiCvADGksDBQ/QBuR2/CpRjNTHfObkRDbiOC0BhMaGbYhjfuKgdd+6BL6vrIzyoW5F1o kQqfS0c6EcnMza+UVXf2lJLvqiExxZtL48UyoriVzqTQ39RshAmY95152sBWCV1GGhe9 s+3ECbSSOMGWYC1Dzp/Saq6k6LuPGl8QH2KUCV6Yvh5cKXQ74nBtm4vl2D3L9uPU37Om SU4LxiFQyFR/gq+iDWTG4PcoMqHdaQFPi9dQSEnY3c/8UZuDVjU8f+yJQtqRNBIpt3gp j70g== X-Gm-Message-State: AOJu0YxVcI+WCKlYvbf0EmP4ITiWICk0DvgfgtWrH0DGWB2Tfc0h9I25 dM/W5wGquw1gVGfkohpmpxB5TrzVHwe56GGPMJUmj4MBybu7MibOfqzpZQIZ X-Received: by 2002:a17:907:a0cc:b0:a45:f71e:9e49 with SMTP id hw12-20020a170907a0cc00b00a45f71e9e49mr4153077ejc.67.1710173673557; Mon, 11 Mar 2024 09:14:33 -0700 (PDT) Received: from mariano ([188.210.239.79]) by smtp.gmail.com with ESMTPSA id w13-20020a17090652cd00b00a45b944681dsm2953593ejn.217.2024.03.11.09.14.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 Mar 2024 09:14:32 -0700 (PDT) Received: by mariano (Postfix, from userid 1000) id 56ECDBFCE2; Mon, 11 Mar 2024 17:14:31 +0100 (CET) From: Stefano Sabatini To: FFmpeg development discussions and patches Date: Mon, 11 Mar 2024 17:14:31 +0100 Message-Id: <20240311161431.323249-3-stefasab@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240311161431.323249-1-stefasab@gmail.com> References: <20240311161431.323249-1-stefasab@gmail.com> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 3/3] doc/muxers/fifo: review documentation X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Cc: Stefano Sabatini Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: QcHfxaBcNgy3 --- 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.