[FFmpeg-devel,4/6] doc/muxers: add mkvtimestamp_v2

---
 doc/muxers.texi | 8 ++++++++
 1 file changed, 8 insertions(+)

Stefano Sabatini:
> ---
>  doc/muxers.texi | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/doc/muxers.texi b/doc/muxers.texi
> index f94513527d..490d5557bf 100644
> --- a/doc/muxers.texi
> +++ b/doc/muxers.texi
> @@ -2933,6 +2933,14 @@ MicroDVD subtitle format muxer.
>  
>  This muxer accepts a single @samp{microdvd} subtitles stream.
>  
> +@section mkvtimestamp_v2
> +mkvtoolnix v2 timecode format muxer.
> +
> +Write the PTS rawvideo frame to the output, as supported by the
> +@command{mkvextact} tool from the @command{mkvtoolnix} suite.
> +
> +This muxer accepts a single @samp{rawvideo} stream.
> +
>  @section mp3
>  
>  The MP3 muxer writes a raw MP3 stream with the following optional features:

This is wrong: MKVToolNix switched to "# timestamp format v2" a long
time ago (we still write the old "# timecode format v2" header);
furthermore, MKVToolNix actually uses pts (which it reorders to be
ascending), not dts like our muxer. Furthermore MKVToolNix does not
force a 1ms precision on timestamps.

- Andreas

PS: mkvextract, not mkvextact.

On date Tuesday 2024-04-16 12:50:19 +0200, Andreas Rheinhardt wrote:
> Stefano Sabatini:
> > ---
> >  doc/muxers.texi | 8 ++++++++
> >  1 file changed, 8 insertions(+)
> > 
> > diff --git a/doc/muxers.texi b/doc/muxers.texi
> > index f94513527d..490d5557bf 100644
> > --- a/doc/muxers.texi
> > +++ b/doc/muxers.texi
> > @@ -2933,6 +2933,14 @@ MicroDVD subtitle format muxer.
> >  
> >  This muxer accepts a single @samp{microdvd} subtitles stream.
> >  
> > +@section mkvtimestamp_v2
> > +mkvtoolnix v2 timecode format muxer.
> > +
> > +Write the PTS rawvideo frame to the output, as supported by the
> > +@command{mkvextact} tool from the @command{mkvtoolnix} suite.
> > +
> > +This muxer accepts a single @samp{rawvideo} stream.
> > +
> >  @section mp3
> >  
> >  The MP3 muxer writes a raw MP3 stream with the following optional features:
> 

> This is wrong: MKVToolNix switched to "# timestamp format v2" a long
> time ago (we still write the old "# timecode format v2" header);
> furthermore, MKVToolNix actually uses pts (which it reorders to be
> ascending), not dts like our muxer. Furthermore MKVToolNix does not
> force a 1ms precision on timestamps.

Correct.

I compared the output of the muxer and of mkvtoolnix extract
timestamp_v2 and I'm not yet clear about the timestamp differences I'm
observing (the muxer output maps with the timestamps, the mkvtoolnix
timestamps differ by a few ms). But I think also mkvtoolnix use a 1ms
timebase.

Also, IIRC there is no generic way to reorder PTSs, so this might
account for another difference which might be difficult to implement
generically.

Stefano Sabatini:
> On date Tuesday 2024-04-16 12:50:19 +0200, Andreas Rheinhardt wrote:
>> Stefano Sabatini:
>>> ---
>>>  doc/muxers.texi | 8 ++++++++
>>>  1 file changed, 8 insertions(+)
>>>
>>> diff --git a/doc/muxers.texi b/doc/muxers.texi
>>> index f94513527d..490d5557bf 100644
>>> --- a/doc/muxers.texi
>>> +++ b/doc/muxers.texi
>>> @@ -2933,6 +2933,14 @@ MicroDVD subtitle format muxer.
>>>  
>>>  This muxer accepts a single @samp{microdvd} subtitles stream.
>>>  
>>> +@section mkvtimestamp_v2
>>> +mkvtoolnix v2 timecode format muxer.
>>> +
>>> +Write the PTS rawvideo frame to the output, as supported by the
>>> +@command{mkvextact} tool from the @command{mkvtoolnix} suite.
>>> +
>>> +This muxer accepts a single @samp{rawvideo} stream.
>>> +
>>>  @section mp3
>>>  
>>>  The MP3 muxer writes a raw MP3 stream with the following optional features:
>>
> 
>> This is wrong: MKVToolNix switched to "# timestamp format v2" a long
>> time ago (we still write the old "# timecode format v2" header);
>> furthermore, MKVToolNix actually uses pts (which it reorders to be
>> ascending), not dts like our muxer. Furthermore MKVToolNix does not
>> force a 1ms precision on timestamps.
> 
> Correct.
> 
> I compared the output of the muxer and of mkvtoolnix extract
> timestamp_v2 and I'm not yet clear about the timestamp differences I'm
> observing (the muxer output maps with the timestamps, the mkvtoolnix
> timestamps differ by a few ms). But I think also mkvtoolnix use a 1ms
> timebase.

The accuracy of the timestamps output by mkvextract is determined by the
TimestampScale of the file in question; it is most often 1ms when the
file has video.
You need to provide more details if you want these discrepancies to be
analyzed.

> 
> Also, IIRC there is no generic way to reorder PTSs, so this might
> account for another difference which might be difficult to implement
> generically.

Write them into a buffer and reorder them at the end?
(No, I have no intention to actually implement this. I am rather leaning
to "this muxer should not exist".)

- Andreas

On date Tuesday 2024-04-16 20:09:19 +0200, Andreas Rheinhardt wrote:
> Stefano Sabatini:
> > On date Tuesday 2024-04-16 12:50:19 +0200, Andreas Rheinhardt wrote:
> >> Stefano Sabatini:
> >>> ---
> >>>  doc/muxers.texi | 8 ++++++++
> >>>  1 file changed, 8 insertions(+)
> >>>
> >>> diff --git a/doc/muxers.texi b/doc/muxers.texi
> >>> index f94513527d..490d5557bf 100644
> >>> --- a/doc/muxers.texi
> >>> +++ b/doc/muxers.texi
> >>> @@ -2933,6 +2933,14 @@ MicroDVD subtitle format muxer.
> >>>  
> >>>  This muxer accepts a single @samp{microdvd} subtitles stream.
> >>>  
> >>> +@section mkvtimestamp_v2
> >>> +mkvtoolnix v2 timecode format muxer.
> >>> +
> >>> +Write the PTS rawvideo frame to the output, as supported by the
> >>> +@command{mkvextact} tool from the @command{mkvtoolnix} suite.
> >>> +
> >>> +This muxer accepts a single @samp{rawvideo} stream.
> >>> +
> >>>  @section mp3
> >>>  
> >>>  The MP3 muxer writes a raw MP3 stream with the following optional features:
> >>
> > 
> >> This is wrong: MKVToolNix switched to "# timestamp format v2" a long
> >> time ago (we still write the old "# timecode format v2" header);
> >> furthermore, MKVToolNix actually uses pts (which it reorders to be
> >> ascending), not dts like our muxer. Furthermore MKVToolNix does not
> >> force a 1ms precision on timestamps.
> > 
> > Correct.
> > 
> > I compared the output of the muxer and of mkvtoolnix extract
> > timestamp_v2 and I'm not yet clear about the timestamp differences I'm
> > observing (the muxer output maps with the timestamps, the mkvtoolnix
> > timestamps differ by a few ms). But I think also mkvtoolnix use a 1ms
> > timebase.
> 
> The accuracy of the timestamps output by mkvextract is determined by the
> TimestampScale of the file in question; it is most often 1ms when the
> file has video.

> You need to provide more details if you want these discrepancies to be
> analyzed.

Probably not worth the effort.

> > Also, IIRC there is no generic way to reorder PTSs, so this might
> > account for another difference which might be difficult to implement
> > generically.
> 

> Write them into a buffer and reorder them at the end?
> (No, I have no intention to actually implement this. I am rather leaning
> to "this muxer should not exist".)

I also think we have better tools at this point (one being ffprobe
-show_packets) but we should not drop it before deprecating it.

Plan: av_tree to insert elements in a constant-size buffer or store in
a buffer sorted once at the end. We probably should skip PTS=NA
elements.

Dropping the doc patch as the implementation is broken. 

Will apply the rest of the patchset soon.