PR #25364 opened by Forgejo_Fairy URL: https://code.ffmpeg.org/FFmpeg/FFmpeg/pulls/25364 Patch URL: https://code.ffmpeg.org/FFmpeg/FFmpeg/pulls/25364.patch
Input property changes can rebuild an entire filtergraph, resetting downstream counters and discarding buffered frames even when a scaler maintains fixed output dimensions. Document a normalization graph followed by a wrapped_avframe loopback and a separate stateful graph. The wrapper passes references to uncompressed frames, and the null output avoids an intermediate media file. The example preserves select's counter across the resolution change in #25314. Explain that downstream input properties must remain stable and that frames buffered in the normalization graph can still be lost. Validation on arm64 Linux at master 303510f9d1fe and the reporter's revision 20b009e30136: - The documented command selects only PTS 5 from the supplied 20-frame changing-resolution input. - Replacing select with reverse preserves all 20 frames, with frame records identical to the single-graph reinit_filter=0 control. - POD generation, pod2man, and git diff --check pass. Direct filtergraph chaining was also tested: select retains its counter, but downstream reverse produces no frames even for constant-format input because of a separate EOF-signalling problem. This documentation change does not fix that problem or introduce automatic partial graph reconfiguration. Related to #25314. >From 0a6b3a218a406261fd48d7e1f45ab36df1c0f64f Mon Sep 17 00:00:00 2001 From: Michael Niedermayer <[email protected]> Date: Thu, 22 Oct 2026 16:54:07 +0000 Subject: [PATCH] doc/ffmpeg: document a state-preserving normalization boundary Use a wrapped_avframe loopback to isolate downstream state from input graph reinitialization without an intermediate compressed stream or file. Document the stable-property requirement and the remaining upstream buffering limitation. Related to #25314. Assisted-by: Fairy --- doc/ffmpeg.texi | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi index d31678f8d8c..4cf14f69c85 100644 --- a/doc/ffmpeg.texi +++ b/doc/ffmpeg.texi @@ -1436,6 +1436,31 @@ The properties where a change triggers reinitialization are, for video, frame resolution or pixel format; for audio, sample format, sample rate, channel count or channel layout. +To preserve state in downstream filters, normalization can be placed in a +separate filtergraph and its output passed through a @code{wrapped_avframe} +loopback decoder (see @ref{Loopback decoders}). This encoder and decoder pass +references to uncompressed frames within the process; the @code{null} output +does not write an intermediate file. + +For example, for a 10 fps H.264 input whose resolution changes: +@example +ffmpeg -r 10 -i changing.h264 \ + -filter_complex '[0:v]scale=128:72,format=yuv420p[normalized]' \ + -map '[normalized]' -c:v wrapped_avframe -fps_mode passthrough -f null - \ + -dec 0:0 -filter_complex '[dec:0]select=eq(n\,5)[selected]' \ + -map '[selected]' -fps_mode passthrough -f framemd5 selected.framemd5 +@end example + +The first graph may be reinitialized, while the second graph retains its +frame counter and selects only the sixth frame overall. Stateful or buffering +filters belong in the second graph: frames buffered in the first graph can +still be lost when it is reinitialized. + +The example assumes a constant display aspect ratio and no changes to other +frame properties. The boundary must provide stable input properties for the +downstream graph; fixing resolution and pixel format alone is insufficient +for arbitrary changes to color properties, side data, or hardware frames. + @item -drop_changed[:@var{stream_specifier}] @var{integer} (@emph{input,per-stream}) This boolean option determines whether a frame with differing frame parameters mid-stream gets dropped instead of leading to filtergraph reinitialization, as that would lead to loss -- 2.54.0 _______________________________________________ ffmpeg-devel mailing list -- [email protected] To unsubscribe send an email to [email protected]
