-
Notifications
You must be signed in to change notification settings - Fork 3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add media zero timecode and start of programme timecode metadata #240
Conversation
Makes sense to me. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nothing to change from me...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Approved this time!
Why do we need a |
The Timed Text Working Group just discussed
The full IRC log of that discussion<nigel> Subtopic: Add legacy metadata structure and media zero timecode metadata #240<nigel> github: https://github.com//pull/240 <nigel> Cyril: I added my comment already. Why add the legacy structure? <nigel> .. Why make it an element not an attribute, e.g. on the tt element? <nigel> Nigel: I wanted to provide a home for legacy conversion data, and to make it really clear that <nigel> .. it isn't something that should carry any presentation semantics. <nigel> .. We could do it the way you suggest, of course. <nigel> .. I fear that people won't read the spec and putting the data here gives a really strong hint. <nigel> Cyril: I think I raised the point in the past - it's not specific to DAPT, it could be a TTML thing. <nigel> .. I understand that we need it in DAPT, but maybe we could define it in the TTML namespace, and transfer <nigel> .. it into TTML2 later. <atai> q+ <nigel> Nigel: I'm happy to consider other use cases, I actually don't know of any right now. <nigel> ack at <nigel> Andreas: I was present when we started the discussion but haven't followed the current solution of the issue. <nigel> .. When we started I also had the feeling that it could have wider applicability than DAPT, and have other use cases, <nigel> .. so would be better in another namespace, or aligned with the parent specification. <nigel> .. Sorry for not fully reviewing what you have proposed here. <nigel> .. What we have in EBU-TT, couldn't the same thing be expressed with what you propose here for DAPT? <nigel> Nigel: I don't think so, happy to be shown otherwise. <nigel> .. Need to close for time, please continue to review and discuss. <nigel> .. Wonder how strong your feeling is about the data structure as proposed, Cyril? <nigel> Cyril: I don't understand the point of the legacy metadata, why it's different from other conversion data. <nigel> .. Also would like to see an informative reference to ESEF to explain it. <nigel> SUMMARY: Review to continue |
@cconcolato The idea is to clearly mark out data that is not core to the content, and is definitely not expected to be required or processed for presentation, but is only needed to retain information that was part of the legacy source file, which may need to be resolved later. I'd happily add some descriptive text to try to explain this more. We could consider other names too. Re EBU-TT metadata, which is in EBU-TT part M, Metadata Definitions, EBU Tech 3390, defines most of the entities as elements, not attributes: doing this means that if anyone needs to add some custom metadata they have the ability to add attributes to the element. An alternative that you mentioned in yesterday's call is to define an attribute that would live on the root |
That is already conveyed with the metadata signaling (qualified namespace on the attribute or when used on the element).
This raises a lot of questions for me:
Understood, but
It could make sense for some structured vocabulary, but in this case where there is just one timecode value to carry, defining 2 elements is too complex.
I don't understand why you think people would think it would be needed in all cases, if it is optional. It feels natural to me to have document-wide attributes be on the top-level element. My strong preference is to have it as an attribute and not to introduce unnecessary elements. |
Some additional comments:
This gives the impression that there is always a Script Event at time 0. It should be rephrased to say things like 'hypothetical'.
The word 'conundrum' seems too strong. It is a rather straightforward algorithm. |
Good catch, thank you.
It's a conundrum for the person converting the legacy (e.g. ESEF) files, who has no access to the data they apparently need. |
That's not correct, it's an element.
Right, one so far...
Unfortunately I've seen plenty of misunderstandings and weird/unhelpful/not-as-intended documents from people who haven't taken the time to read the spec properly. I think the fear is reasonably well founded.
Yes, we could put it there instead.
Yes, to an extent, but again, my experience is that people look past namespaces.
Since its metadata, this isn't so much about semantics as about guidance and real world usage. In my way of thinking, data should be put here if it is a) not otherwise needed/used/represented in DAPT, and b) still needed for some later purpose because of the workflow, or needed to support the transition to DAPT.
Yes, we could omit this altogether and allow people to define and use their own custom data; the reason for trying to resolve this issue within the DAPT specification is because we expect it to be a widespread issue for people coming from ESEF in particular.
OK, so you are in favour of organising the metadata in some way. Doesn't the addition of a legacy metadata child of |
I think adding a legacy metadata element seems like a cleaner approach, given that it will function as a container for values that will only be meaningful in the context it represents:
Ordinarily my instinct would be to add them as attributes for the reasons Cyril suggests, but I think it makes sense to group them under an element that can dispensed with for natively originated documents. I think anyone dealing with legacy files in volume at the time of adoption would appreciate having these two values logically grouped together but separately. |
9a39f10
to
b61c349
Compare
I stand corrected. I guess it feels so unnatural to me to use elements for that that I persuaded myself it was an attribute ...
I meant: one for
It does not feel sufficient to introduce an element and just provide guidance on how to use it without clear normative semantics.
I'd rather have a stricter set of rules, like do not put additional vocabulary anywhere except in the legacy element. Otherwise, an implementation will have to deal with both approaches ...
The use case of ESEF can be solved in many ways. If we provide a clear example, people will follow it. We could also go with strict semantics.
Yes, but I'd like implementations to be simple.
It would if a) it had clear, normative semantics to make it unambiguous for authors and simple to implement for parsers. and b) probably the name was changed, like
It seems easier to discard an entire metadata element than to check the type of every child element.
We already have a sentence that says:
|
Should we mandate that there be at most 1 metadata in head and in script events? |
I'm not sure I've ever seen a use case for multiple |
Raised as #242. |
index.html
Outdated
@@ -886,6 +886,152 @@ <h5>Timing Properties</h5> | |||
</p> | |||
</section> | |||
</section> | |||
|
|||
<section> | |||
<h4>Deferred resolution of timecode-based synchronisation</h4> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we simply rename this section "timecode-related metadata"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, I would prefer if this section, which is essentially about handling of metadata, would be grouped together with the existing section 5.2.3 (also about general metadata) in either a new top level section that deals with metadata generally, or even in an Annex.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it makes sense to move it to an appendix.
index.html
Outdated
<p>In workflows that create <a>DAPT documents</a> by conversion from formats | ||
that synchronise content using timecode to match time stamps | ||
in the <a>related media object</a>, | ||
a common issue occurs if the timecode of | ||
the beginning of the media is not known at the time of conversion. | ||
</p> | ||
<p>The optional <a>Media Zero Timecode</a> and | ||
<a>Start of Programme Timecode</a> properties can be used to | ||
identify when there is a possible synchronisation error, | ||
and to resynchronise the document when all | ||
the required information is known.</p> | ||
<p>These properties are provided as metadata only and | ||
are not intended to be used to perform direct synchronisation offsets | ||
during presentation. | ||
</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm still trying to understand the feature here and how it differs from the existing EBU-TT feature.
Is the proposed text trying to say the following:
As defined in TTML2, each DAPT document has a timeline on which Script Events are positioned using their begin attributes. For synchronization purposes it is useful to map the DAPT document timeline with the related media object timeline.
In some cases, the mapping is simple, e.g. media time 0 in the related media object corresponds to the origin of the DAPT document timeline. In other cases, a timecode may be necessary. DAPT provides the ability to provide 2 different timecodes:
- The "Start of the Programme Timecode" is the timecode of the time instant in the related media object corresponding to the origin of the DAPT document timeline. It is represented in a DAPT document by a documentStartOfProgramme element, defined in EBUT-TT, using the EBU-TT namespace, located in a metadata element in the head.
(and either one of the alternatives below)
- The "Media Zero Timecode" is the timecode of the first media data in the related media object. It is represented in DAPT documents by the mediaZeroTimecode element, in the DAPT namespace, located in a metadata element in the head.
- The "First Script Event Timecode" is the timecode of the time instant in the related media object corresponding to the first script event in the DAPT document. It is represented in DAPT documents by the XXX element, in the DAPT namespace, located in a metadata element in the head.
NOTE: Depending on the script and related media object workflows, there may not be a timecode in the related media object corresponding to the origin of the DAPT document timeline, for example if the related media object has been edited to remove some data at its start. In that case, either the "Start of the Programme Timecode" and all the Script Event begin times have to be edited, or alternatively the "Start of the Programme Timecode" cannot be used but the "First Script Event Timecode" or "Media Zero Timecode" can be used.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, very much not that!
Start of programme timecode is the timecode in the related media corresponding to the beginning of the related media object's programme content.
Media Zero timecode is a timecode that media time zero in the DAPT document maps to.
If the DAPT document is not synchronised to the related media object's programme content, those two values will differ.
If the start of programme timecode is unknown, then you don't know if they're in sync or not.
If both are present and the same, then you have some reassurance that the DAPT document is synchronised with the media.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the timecode of the time instant in the related media object corresponding to the origin of the DAPT document timeline
The issue is that documents that are not synchronised to the related media object do not satisfy the "corresponding to the origin of the DAPT document timeline" part of this sentence.
In discussion with @cconcolato we realised that Media Zero Timecode was confusing, since it wasn't obvious which media was meant - it needs to mean "media timebase in the DAPT document" not "timecode at the beginning of the media". Changed to "DAPT Origin Timecode" in ed1f5de. |
index.html
Outdated
<p><a>DAPT Documents</a> express time as <em>media time</em>, | ||
which assumes that there is a reference start time (zero) on a media | ||
timeline, and a fixed playrate. | ||
An alternative scheme that is used in some workflows is to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the wording is ambiguous. Some workflows that use DAPT? No, I think it is meant to say: "used for some other script formats than DAPT"
index.html
Outdated
timeline, and a fixed playrate. | ||
An alternative scheme that is used in some workflows is to | ||
synchronise media components using timecode, | ||
time stamps that are applied, for example to each frame of video. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is "time stamps that are applied" intended? It feels like left over text. Suggest delete it.
time stamps that are applied, for example to each frame of video. | |
for example to each frame of video. |
index.html
Outdated
time stamps that are applied, for example to each frame of video. | ||
</p> | ||
<p>Workflows that create <a>DAPT documents</a> from | ||
resources that use timecode need to map the timecode |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"resources" can be confused with media resources (MPEG-2 TS, ProRes, ...) that can still use timecodes.
resources that use timecode need to map the timecode | |
script formats other than DAPT that use timecode need to map the timecode |
index.html
Outdated
<p>If this mapping is not correct, presentation of the | ||
<a>DAPT Document</a> will not be synchronised with the <a>related media object</a>. | ||
In order to achieve correct synchronisation in this scenario, | ||
the timecode corresponding to the start of the programme needs to be known.</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the timecode corresponding to the start of the programme needs to be known.
This is too strong. Having one timecode is sufficient. It could be the first content timecode.
the timecode corresponding to the start of the programme needs to be known.</p> | |
a timecode, such as the one corresponding to the start of the programme, needs to be known.</p> |
index.html
Outdated
<p>If the start of programme timecode is not known, | ||
but timecodes corresponding to <a>Script Events</a> are known, | ||
it is still possible to construct a <a>DAPT Document</a>, | ||
albeit one whose synchronisation with the related media is uncertain.</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you expect the person reading "uncertain" to understand?
index.html
Outdated
<p>These properties are provided as metadata only and | ||
are not intended to be used to perform direct synchronisation offsets | ||
during presentation.</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should add:
In particular, when the related media object uses timecode, the presence of the timecode properties does not mean that the player needs to relate these timecode values with any timecode value embedded in the related media resource.
<p>The optional <a>DAPT Origin Timecode</a> and | ||
<a>Start of Programme Timecode</a> properties can be used to | ||
identify when there is a possible synchronisation error, | ||
and to resynchronise the document when all | ||
the required information is known.</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If my understanding is correct I would suggest replacing with the following text
The properties can be used to provide timecodes from the related media object or from any other script format used to produce the DAPT document, and are informational. However, when they are both provided and differ, it is an indication that the DAPT document is not synchronized with the related media object and that processing of the script event begins is needed. To achieve synchronization, the following needs to be done:
- The difference DAPT Origin Timecode minus the Start of Programme Timecode is computed as "delta". It may be positive or negative.
- Each Script begin value X shall be changed to X + delta.
- The DAPT Origin Timecode shall be removed or changed to the Start of Programme timecode value.
index.html
Outdated
<section> | ||
<h5>DAPT Origin Timecode</h5> | ||
<p>The optional <dfn>DAPT Origin Timecode</dfn> allows a timecode value to be declared | ||
that corresponds to the zero point on the media timeline, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
that corresponds to the zero point on the media timeline, | |
that corresponds to the zero point of the DAPT document timeline, |
index.html
Outdated
<p>The optional <dfn>DAPT Origin Timecode</dfn> allows a timecode value to be declared | ||
that corresponds to the zero point on the media timeline, | ||
that is, the time of a hypothetical <a>Script Event</a> whose <a>Begin</a> is | ||
zero seconds on the media timeline.</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
zero seconds on the media timeline.</p> | |
zero seconds.</p> |
<p class="note">See also <a href="#ttp-framerate"></a>. | ||
No mechanism is defined here for declaring a different frame rate for the <a>DAPT Origin Timecode</a> | ||
than is used for other frame-based time expressions. | ||
</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
</p> | |
</p> | |
<p>If the related media object contains a timecode for the video frame synchronized to the origin of the DAPT document timeline, the DAPT origin timecode shall be equal that timecode. | |
</p> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Approving it technically, may need to do some editorial changes during CR phase.
* Rename the "Legacy Metadata" section to "Deferred resolution of timecode-based synchronisation" * Remove the Legacy Metadata object - the relevant metadata can be put directly into the `tt/head/metadata` element. * Add `ebuttm:documentStartOfProgramme` as "Start of Programme Timecode" * Explain how, by looking at both properties, it is possible to infer whether correct synchronisation has been achieved, and if not, how to resolve it. * Note that this incorrect frame rates or playback rates are not addressed by this method. * Add `ebuttm` namespace prefix.
It was confusing which "media" was meant by Media Zero Timecode.
76243e2
to
c1401ee
Compare
Closes #232.
Adds:
#mediaZeroTimecode
, disposition PermittedWould appreciate review comments from @ewanrsmith - I don't seem to be able to request a review from him.
Updated 2026-09-25 to remove the
<legacy>
object and add the Start of Programme Timecode objectPreview | Diff