[FFmpeg-devel] [PATCH] Complete rewrite of the "fps" video filter section. More accurate.
From: Jim DeLaHunt
This is a complete rewrite of the documentation for the "fps" video
filter. It describes the filter's behaviour more clearly and accurately.
I based the rewrite on reading the source code in vf_fps.c closely.
No code, or other documentation files, are touched by this change.
Signed-off-by: Jim DeLaHunt
---
doc/filters.texi | 167 ++-
1 file changed, 149 insertions(+), 18 deletions(-)
diff --git a/doc/filters.texi b/doc/filters.texi
index 71a6787289..bd4a1ad2a9 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -11139,27 +11139,34 @@ format=pix_fmts=yuv420p|yuv444p|yuv410p
@anchor{fps}
@section fps
-Convert the video to specified constant frame rate by duplicating or dropping
-frames as necessary.
+Generate a video, having the specified constant frame rate, from the frames of
+the input video, by copying or duplicating or dropping input frames based on
+their input presentation time stamps (PTSs). The output video has new PTSs.
You
+can choose the method for rounding from input PTS to output PTS.
It accepts the following parameters:
@table @option
@item fps
-The desired output frame rate. The default is @code{25}.
+The output frame rate, as a number of frames per second. This value can be an
+integer, real, or rational number, or an abbreviation. The default is
@code{25}.
@item start_time
-Assume the first PTS should be the given value, in seconds. This allows for
-padding/trimming at the start of stream. By default, no assumption is made
-about the first frame's expected PTS, so no padding or trimming is done.
-For example, this could be set to 0 to pad the beginning with duplicates of
-the first frame if a video stream starts after the audio stream or to trim any
-frames with a negative PTS.
+The time, in seconds from the start of the input stream, which is converted to
+an input starting PTS value and an output starting PTS value.
+If set, @var{fps} drops input frames
+which have PTS values less than the input starting PTS. If not set, the input
+and output starting PTS values are zero, but @var{fps} drops no input frames
based
+on PTS.
+(See details below.)
@item round
-Timestamp (PTS) rounding method.
+Rounding method to use when calculating output Presentation Timestamp
+(PTS) integer values from input PTS values. If the calculated output PTS value
+is not exactly an integer, then the method determines which of the two
+neighbouring integer values to choose.
-Possible values are:
+Possible method names are:
@table @option
@item zero
round towards 0
@@ -11170,43 +11177,167 @@ round towards -infinity
@item up
round towards +infinity
@item near
-round to nearest
+round to nearest (and if exactly at midpoint, away from 0)
@end table
The default is @code{near}.
@item eof_action
-Action performed when reading the last frame.
+Action which @var{fps} takes with the final input frame. The input video passes
+in an ending input PTS, which @var{fps} converts to an ending output PTS.
+@var{fps} drops any input frames with a PTS at or after this ending PTS.
Possible values are:
@table @option
@item round
-Use same timestamp rounding method as used for other frames.
+Use same rounding method as for other frames, to convert the ending input PTS
+to output PTS.
+
@item pass
-Pass through last frame if input duration has not been reached yet.
+Round the ending input PTS using @code{up}. This can have the effect of passing
+through one last input frame.
@end table
+
The default is @code{round}.
@end table
-Alternatively, the options can be specified as a flat string:
+Alternatively, the options may be specified as a flat string:
@var{fps}[:@var{start_time}[:@var{round}]].
+@var{fps} generates an output video with integer Presentation Time Stamp (PTS)
+values which increment by one each output frame, and with a time base set to
+the inverse of the given frame rate. @var{fps} copies, duplicates, or drops
+input frames, in sequence, to the output video. It does so according to their
+input PTS values, as converted to seconds (via the input time base), then
+rounded to output PTS values.
+
+@var{fps} sets output PTS values in terms of a time line which starts at
+zero. The integer PTS value multipled by the output time base gives a point
+in seconds of that output frame on that timeline. If the @var{start_time}
+parameter is not set, or is zero, the first output frame's PTS value is zero.
+Otherwise, the first PTS value is the output starting PTS value calculated
+from the @var{start_time} parameter.
+
+@var{fps} interprets input PTS values in terms of the same time line. It
+multiplies the input PTS value by the input time base time, to get a frame
+position in seconds on the time line. It rounds that position to an integer
+output PTS value. For example, if the input video has a frame rate
+of 30 fps, a time base of 1/30 seconds, and its first frame has a
+PTS of 300, the
[FFmpeg-devel] [PATCH v2] doc/filters.texi: complete rewrite of fps filter doc, v2.
Thank you for the review. Here is a rewrite of the improvement to the fps filter documentation, based on those comments. Thought it was too wordy before? It now has 11% fewer words. To confirm, no other documentation and no code are affected by this patch. Comments? —Jim DeLaHunt, software engineer, Vancouver, Canada ___ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
[FFmpeg-devel] [PATCH v2] doc/filters.texi: complete rewrite of fps filter doc, v2.
From: Jim DeLaHunt
Fix unclear wording and spelling mistakes based on review.
Reduce overall word count by 11%. Ready for patch review.
No other docs, and no executable code, are changed.
Signed-off-by: Jim DeLaHunt
---
doc/filters.texi | 157 +--
1 file changed, 138 insertions(+), 19 deletions(-)
diff --git a/doc/filters.texi b/doc/filters.texi
index d19fd346ae..0d7d15c448 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -11194,25 +11194,30 @@ format=pix_fmts=yuv420p|yuv444p|yuv410p
@anchor{fps}
@section fps
-Convert the video to specified constant frame rate by duplicating or dropping
-frames as necessary.
+Make a new video from the frames and presentation time stamps (PTSs) of the
+input. The new video has a specified constant frame rate, and new PTSs. It
+generally keeps frames from the old video, but might repeat or drop some
frames.
+You can choose the method for rounding from input PTS to output PTS. This
+affects which frames @var{fps} keeps, repeats, or drops.
It accepts the following parameters:
@table @option
@item fps
-The desired output frame rate. The default is @code{25}.
+The output frame rate, in frames per second. May be an integer, real, or
+rational number, or an abbreviation. The default is @code{25}.
@item start_time
-Assume the first PTS should be the given value, in seconds. This allows for
-padding/trimming at the start of stream. By default, no assumption is made
-about the first frame's expected PTS, so no padding or trimming is done.
-For example, this could be set to 0 to pad the beginning with duplicates of
-the first frame if a video stream starts after the audio stream or to trim any
-frames with a negative PTS.
+A time, in seconds from the start of the input stream, which @var{fps}
converts
+to an input starting PTS and an output starting PTS. If set,
+@var{fps} drops input frames which have PTSs less than the input starting
+PTS. If not set, the input and output starting PTSs are zero, but
+@var{fps} drops no input frames based on PTS. (See details below.)
@item round
-Timestamp (PTS) rounding method.
+Rounding method to use when calculating output PTSs from input PTSs.
+If the calculated output PTS is not exactly an integer, then the value
+determines which neighbouring integer value @var{fps} selects.
Possible values are:
@table @option
@@ -11225,43 +11230,157 @@ round towards -infinity
@item up
round towards +infinity
@item near
-round to nearest
+round to nearest (midpoints round away from 0)
@end table
The default is @code{near}.
@item eof_action
-Action performed when reading the last frame.
+Action which @var{fps} takes with the final input frame. The input video passes
+in a final input PTS, which @var{fps} converts to an output PTS limit.
+@var{fps} drops any input frames with a PTS at or after this limit.
Possible values are:
@table @option
@item round
-Use same timestamp rounding method as used for other frames.
+Use same rounding method as for other frames.
+
@item pass
-Pass through last frame if input duration has not been reached yet.
+Round the ending input PTS using @code{up}. This might make @ref{fps} include
+one last input frame.
@end table
+
The default is @code{round}.
@end table
-Alternatively, the options can be specified as a flat string:
+Alternatively, the options may be specified as a flat string:
@var{fps}[:@var{start_time}[:@var{round}]].
-See also the @ref{setpts} filter.
+@var{fps} makes an output video with consecutive integer PTSs, and with a
+time base set to the inverse of the given frame rate. @var{fps} keeps,
repeats,
+or drops input frames, in sequence, to the output video. It does so according
+to their input PTSs, as converted to seconds (via the input time base),
+then rounded to output PTSs.
+
+@var{fps} sets output PTSs in terms of a timeline which starts at
+zero. For any output frame, the integer PTS multiplied by the time base
+gives a value in seconds on that timeline. If the @var{start_time}
+parameter is not set, or is zero, the first output frame's PTS is zero.
+Otherwise, the first PTS is the output starting PTS calculated
+from the @var{start_time} parameter.
+
+@var{fps} interprets input PTSs in terms of the same timeline. It
+multiplies each input frame's PTS by the input time base, to get a value
+in seconds on the timeline. It rounds that value to an integer output PTS.
+For example, if the input video has a frame rate of 30 fps, a time base
+of 1/30 seconds, and a first frame with a PTS of 300, then @var{fps} treats
that
+first frame as occurring 10 seconds (= 300 * 1/30) after the start of the
video,
+even though it is the first frame.
+
+Setting a @code{start_time} value allows for padding/trimming at the
+start of the input. For example, you can set @code{start_time} to 0, to pad
the
+beginning with repeats of the first frame if a video stream starts after
+the audio stream,
