[FFmpeg-user] Filter documentation -- PTSs

[Jim DeLaHunt]

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