Subject: [Cellar] Rename Timecode* elements to Timestamp*

From: Steve Lhomme <[email-masked]>
Date: Mon, 25 Sep 2017 14:02:53 +0200

As many of you know, in Matroska we use(d) the work timecode where in
fact it should be timestamps. It goes as far as names in the code we
use.

This can be confusing for people who can actually tell the difference
between the two. And since we plan to introduce timecodes, it might be
a good idea to make this change.

The XML will keep the old names in the cppname so the generated
code(s) remain unchanged. Also some defines should be added with the
new names and the old ones marked as deprecated.

-- 
Steve Lhomme
Matroska association Chairman

---

From: Kieran O Leary <[email-masked]>
Date: Mon, 25 Sep 2017 13:38:29 +0100

+1

I think this would be great, I find the current naming to be confusing.

---

From: Derek Buitenhuis <[email-masked]>
Date: Mon, 25 Sep 2017 13:40:08 +0100

> I think this would be great, I find the current naming to be confusing. 

A hearty +1 from me too.

Fun fact: my introduction to the FOSS multimedia community on IRC was me arguing
about timecodes being timestamps due to this weird naming ;). Many years ago...

- Derek

---

From: Jerome Martinez <[email-masked]>
Date: Mon, 25 Sep 2017 14:41:47 +0200

> new names and the old ones marked as deprecated.
+1, but we need to put notes about the old name presence in old doc, so 
nobody is surprised to find a different name elsewhere and can "map" the 
old name to the new name by reading the up to date spec.

---

From: Steve Lhomme <[email-masked]>
Date: Mon, 25 Sep 2017 15:19:36 +0200

Here goes the Pull Request:
https://github.com/Matroska-Org/matroska-specification/pull/199

I split the commit in two with one adding the reference to the old
naming as Jerome suggested.

2017-09-25 14:41 GMT+02:00 Jerome Martinez <[email-masked]>:
> nobody is surprised to find a different name elsewhere and can "map" the old
> name to the new name by reading the up to date spec.
>
>
> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar

---

From: Dave Rice <[email-masked]>
Date: Mon, 25 Sep 2017 09:56:14 -0400

> On Sep 25, 2017, at 8:41 AM, Jerome Martinez <[email-masked]> wrote:
> 
> +1, but we need to put notes about the old name presence in old doc, so nobody is surprised to find a different name elsewhere and can "map" the old name to the new name by reading the up to date spec.

-1 for me.

I think this move can cause some unforeseen consequences since it involves renaming several elements such as "Timecode", "TimecodeScale", "ReferenceTimecode" (if still exists). The pairing of these names with the element ids are used within many Matroska Readers such as mkvinfo, mkvtoolnix, mkvparse, mediaconch. The names are also widely used in libavformat. It seems like a large undertaking to coordinate the elements to be renaming in some many tools. Also those trying to research these elements will be so confused since they will be referenced with different names in different places (such as historical mailing lists, forums, etc).

As an alternative proposal, I'd suggest that the current "Timecode" concept of Matroska have it's name expanded to something like "Matroska Timecode" which is defined in relation to the "Timecode" and "TimecodeScale" elements but that those elements are not renamed. Then other timecode formats can be added as Tracks or Tags but with a clarifier that they are not "Matroska Timecode".

Dave Rice

---

From: Tobias Rapp <[email-masked]>
Date: Mon, 25 Sep 2017 16:46:47 +0200

> I think this move can cause some unforeseen consequences since it involves renaming several elements such as "Timecode", "TimecodeScale", "ReferenceTimecode" (if still exists). The pairing of these…

I don't know about mkv* tools or MediaConch but AFAICS there would be no 
user-visible changes in libavformat. And while it's true that renaming 
the element now in Matroska v4 might cause a little confusion I think it 
would be some lost opportunity not fixing the elements before 
standardization.

So +1 from my side.

Regards,
Tobias

---

From: Steve Lhomme <[email-masked]>
Date: Mon, 25 Sep 2017 16:58:55 +0200

2017-09-25 15:56 GMT+02:00 Dave Rice <[email-masked]>:
> I think this move can cause some unforeseen consequences since it involves renaming several elements such as "Timecode", "TimecodeScale", "ReferenceTimecode" (if still exists). The pairing of these names with the element ids are used within many Matroska Readers such as mkvinfo, mkvtoolnix, mkvparse, mediaconch. The names are also widely used in libavformat.

If it's strings that are internal to the code, it doesn't matter what
they are called. I can even do the patches for some projects.

For strings that are presented to the user that might be a problem.
IIRC there's a timecode file format for example in mkvmerge that use
the old name(s). The command line parameters of mkvmerge may differ as
well. But in that case it does not really matter if they match exactly
what's in the specs. But I understand changing the output of a tool
like mkvinfo might be problematic. IIRC it's based on cppname though
or otherwise it has it's on ID<>string correspondance and no need to
change for now.

> It seems like a large undertaking to coordinate the elements to be renaming in some many tools. Also those trying to research these elements will be so confused since they will be referenced with different names in different places (such as historical mailing lists, forums, etc).

These names won't be lost. They will actually be in the specs:
https://github.com/Matroska-Org/matroska-specification/pull/199/commits/4739ec73165785959af256ba65b1f14449655770

> As an alternative proposal, I'd suggest that the current "Timecode" concept of Matroska have it's name expanded to something like "Matroska Timecode" which is defined in relation to the "Timecode"…

But then you're adding some new definition that may not match with
existing programs either.

---

From: Steve Lhomme <[email-masked]>
Date: Mon, 25 Sep 2017 17:03:21 +0200

2017-09-25 16:46 GMT+02:00 Tobias Rapp <[email-masked]>:
>> I think this move can cause some unforeseen consequences since it involves
>> renaming several elements such as "Timecode", "TimecodeScale",
>> "ReferenceTimecode" (if still exists). The pairing of these names with the
>> element ids are used within many Matroska Readers such as mkvinfo,
>> mkvtoolnix, mkvparse, mediaconch. The names are also widely used in
>> libavformat. It seems like a large undertaking to coordinate the elements to
>> be renaming in some many tools. Also those trying to research these elements
>> will be so confused since they will be referenced with different names in
>> different places (such as historical mailing lists, forums, etc).
>
>
> user-visible changes in libavformat. And while it's true that renaming the
> element now in Matroska v4 might cause a little confusion I think it would
> be some lost opportunity not fixing the elements before standardization.

Yes, that's my main point here. We have the last chance to fix this
legacy for good.

---

From: Moritz Bunkus <[email-masked]>
Date: Mon, 25 Sep 2017 20:16:56 +0200

Hey,

for MKVToolNix renaming those things would be a (big) problem. There are
several places where the names and terms are used, with varying degrees of
issues if they're changed:

1. The class names in the code. This is obviously not an issue if the class
   names are kept.

   However, I can foresee issues if we introduce new elements that deal
   with real timecodes (as in timecode tracks). One could imagine an
   element that contains the timecode (real world usage) a cluster starts
   on. In the specs that might be called… Cluster Timecode (as the old one
   would be renamed to Cluster Timestamp). However, in the code the old
   element is still called KaxClusterTimecode — so what should the new
   element be called in the code?

2. Program options and the corresponding documentation: there are several
   options in mkvmerge, mkvextract and mkvpropedit that deal with
   timestamps that are currently named something-timecode-something
   (e.g. `mkvextract file.mkv timecodes_v2 …` or `mkvmerge -o out.mkv
   --timecodes 0:tc.txt input.avi`). For each of those I'd have to add
   additional options named something-timestamp-something and keep the old
   names indefinitely in order not to break existing third-party
   applications.

   The documentation would have to be adjusted as well.

3. File formats. mkvmerge supports several versions of the file format used
   with its `--timecodes` option. Those files contain the word `timecode`,
   too, and I'd have to adjust the parser accordingly.

   Documentation has to be adjusted for this, too.

4. Strings in the GUIs: UI labels, help texts.

5. mkvinfo's output. mkvinfo uses the term `timecode` a lot in its
   user-facing output. As I know there are tons of users out there who
   parse mkvinfo's output and who get very upset each time I change the
   format, I've taken to be much more conservative about these changes.

For options 2 through 5 my translators would have to translate a lot of new
strings, too.

These are the things that I can think of off the top of my head. Of those 5
is the most important one to me by far. At the moment I think I would opt
not to change mkvinfo's output in order not to break existing
applications. That would make the whole endeavour somewhat questionable for
me.

Apart from all the work it would impose on me, I also see the danger of
overlooking consequences such a fundamental change. I'm not even positive
I've thought it through in the context of MKVToolNix, the project I know
the ins and outs of like no other. Standardization also means creating a
stable base for implementations, and this change would be the opposite: a
huge disruption to an already existing, huge software base.

Therefore I have to agree with Dave and -1 such a change.

Kind regards,
mosu

---

From: Steve Lhomme <[email-masked]>
Date: Tue, 26 Sep 2017 09:31:47 +0200

>    element be called in the code?

In this particular case it's easy, there cannot be a Timecode for a
Cluster. There cannot be a timecode scale or track timecode scale
either.

Also if it's a track type there might be specific fields in the track
entry but it will probably be prefixed, similar to KaxVideoPixelWidth
or KaxAudioSamplingFreq.

>    The documentation would have to be adjusted as well.

I don't think this is a huge task. And it is not mandatory even if the
names in the specifications change.

The "--timecodes 0:tc.txt" is more problematic. But it will have to be
handled when (and not if) we add real timecode tracks.

>    Documentation has to be adjusted for this, too.

The file format shouldn't change for the timestamp files, too bad it's
called timecode. But if it was called blahblah people will still need
to read/write it that way.

> 4. Strings in the GUIs: UI labels, help texts.

It might be the trickiest part. But again, that will need to be done
one way or another because timecode tracks are coming.

>    format, I've taken to be much more conservative about these changes.

Yes, IMO that shouldn't change. Or if it becomes a problem with
timecode tracks, have a legacy mode using the old strings and by
default use the new ones (or the other way around).

> huge disruption to an already existing, huge software base.

But the first thing you see in the Timestamp section is that it used
to be called timecodes.

> Therefore I have to agree with Dave and -1 such a change.

Rather than voting I'd prefer reaching a consensus.

---

From: Reto Kromer <[email-masked]>
Date: Tue, 26 Sep 2017 09:37:56 +0200

+1

---

From: Jerome Martinez <[email-masked]>
Date: Tue, 26 Sep 2017 09:42:28 +0200

On 26/09/2017 09:31, Steve Lhomme wrote:
> [...]

This is my concern too.
If we keep the name as is in IETF specs, we "sanctuarize" it, and we may 
have issues when we talk about a time code track.

> default use the new ones (or the other way around).

Not so easy, as there may be other tools handling output after using our 
tools (I have the same issue as mkvinfo with MediaTrace output), e.g. 
output is stored in a database for long term searching, and changing 
words has impact on output previously stored.
Headache.
But I think it is better to do it now rather than handling 
misunderstandings later about timecode being timestamp and timecode 
being really time code.

> Rather than voting I'd prefer reaching a consensus.

+1 ;-).

More seriously, I don't see something in the middle, looks like a binary 
choice :( (we change or we don't).
If no change, this is also like saying that there will be never a change 
in words when it is written once. This is a bit hard, I would say that 
only hexadecimal values should be fixed. In that case, I guess we need 
to put a bit everywhere a "( meaning timestamp)".

Someone with a proposal able to have a consensus?

Jérôme

---

From: Steve Lhomme <[email-masked]>
Date: Tue, 26 Sep 2017 09:55:48 +0200

Maybe it will be easier to reach a consensus when we have Timecode
tracks. So we can delay this change until timecode tracks are (mostly)
done.

2017-09-26 9:42 GMT+02:00 Jerome Martinez <[email-masked]>:
> tools (I have the same issue as mkvinfo with MediaTrace output), e.g. output
> is stored in a database for long term searching, and changing words has
> impact on output previously stored.
> Headache.
> But I think it is better to do it now rather than handling misunderstandings
> later about timecode being timestamp and timecode being really time code.
>
>>
> If no change, this is also like saying that there will be never a change in
> words when it is written once. This is a bit hard, I would say that only
> hexadecimal values should be fixed. In that case, I guess we need to put a
> bit everywhere a "( meaning timestamp)".
>

---

From: Michael Bradshaw <[email-masked]>
Date: Tue, 26 Sep 2017 10:36:49 -0700

I'm in favor of renaming *Timecode* elements to *Timestamp*, with a
footnote added to the spec that mentions their previous historical names.

On Tue, Sep 26, 2017 at 12:55 AM, Steve Lhomme <[email-masked]> wrote:

> output
> misunderstandings
> in

---

From: Dave Rice <[email-masked]>
Date: Tue, 26 Sep 2017 14:06:44 -0400

If considering renaming the Timecode elements then should we consider other elements as well. ChapCountry? Language->TrackLanguage.

Also I'd suggest considering a version bump with the change, so that the changes would apply to Matroska version 5+.

> On Sep 26, 2017, at 1:36 PM, Michael Bradshaw <[email-masked]> wrote:
> 
> I'm in favor of renaming *Timecode* elements to *Timestamp*, with a footnote added to the spec that mentions their previous historical names.
> 
> On Tue, Sep 26, 2017 at 12:55 AM, Steve Lhomme <[email-masked] <mailto:[email-masked]>> wrote:
> 2017-09-26 9:42 GMT+02:00 Jerome Martinez <[email-masked] <mailto:[email-masked]>>:
> >> 2017-09-25 20:16 GMT+02:00 Moritz Bunkus <[email-masked] <mailto:[email-masked]>>:
> >> [...]
> >>
> > [email-masked] <mailto:[email-masked]>
> > https://www.ietf.org/mailman/listinfo/cellar <https://www.ietf.org/mailman/listinfo/cellar>
> 
> 
> 
> --
> Steve Lhomme
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/cellar <https://www.ietf.org/mailman/listinfo/cellar>
>

---

From: Steve Lhomme <[email-masked]>
Date: Tue, 26 Sep 2017 18:26:23 +0000

IMO we can change the mnemonics. The produced data are strictly the same.
They are not tied to the names.
If anyone started an independent specification for Matroska they could also
use their own set of names. As long as the format is interpreted the same.

Ashley might not agree to get rid of ChapCountry.
On Tue 26 Sep 2017 at 20:06, Dave Rice <[email-masked]> wrote:

> If considering renaming the Timecode elements then should we consider
> other elements as well. ChapCountry? Language->TrackLanguage.
>
> Also I'd suggest considering a version bump with the change, so that the
> changes would apply to Matroska version 5+.
>

---

From: Reto Kromer <[email-masked]>
Date: Tue, 26 Sep 2017 20:40:09 +0200

Dave Rice wrote:

>Also I'd suggest considering a version bump with the change, so
>that the changes would apply to Matroska version 5+.

Will the stream change? If so, I am in favour of a version bump,
otherwise I don't see the necessity. I have the impression
latter is the case, but I might be wrong.

Best regards, Reto