On 2021-02-14 15:47, Mark Filipak (ffmpeg) wrote:
…wouldn't it be helpful if filter documentation included how it
generates PTSs?
Filter documentation should include:
…[List of desired items omitted]…
I am in the camp that believes that the measure of adequate FFmpeg
documentation is that it describes what an FFmpeg user needs to know
about the behaviour of that filter, in all respects, without having to
read the source code. By that measure, I believe that FFmpeg's
documentation for almost all filters is inadequate.
The documentation I wrote for the fps filter might be a useful case
study: <http://blog.jdlh.com/en/2020/04/30/ffmpeg-fps-documented/
<http://blog.jdlh.com/en/2020/04/30/ffmpeg-fps-documented/>>. (The case
study is not limited to PTSs.)
I think every filter should have documentation to this level of detail.
In addition, I think there should be a comprehensive glossary for terms
FFmpeg documentation uses, including industry standard terms like "PTS"
(meaning, "Presentation Time Stamp"). This would probably mean 10x the
word count compared to the current documentation. It would also lead to
discovering many bugs, i.e. code behaviour that is revealed to be
unreasonable when described in words.
…I reckon that, except for a few filters, the important metric is PTS,
not the frame #s assigned at a filter's input node nor its wall-clock
arrival time at a filter's input node. For example, 'interleave'
performs frame interleaves based on the PTSs of incoming frames….
I suspect the generalisation, "the important metric is PTS", will not
prove true for all filters. Another metric might be the most important
for some filters. However, I agree that, for most filters, PTS behaviour
will be an important metric that should be documented.
…There are several of us who are critical. If allowed, we could
resolve all issues for all filters in just a few days….
I'm not sure what you mean by "critical". Do you mean, "people who are
necessary", or "people who criticise"? And, I don't think the people who
criticise could resolve "all issues for all filters in just a few days".
It would take months to read source code, write draft documentation,
review it, and correct it. However, I agree that there could be big
improvements in "just a few days". There are so many documentation
sections which so badly need improvement.
Best regards,
—Jim DeLaHunt
_______________________________________________
ffmpeg-user mailing list
[email protected]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user
To unsubscribe, visit link above, or email
[email protected] with subject "unsubscribe".
