Skip to content
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 T_QUICKTIME codec mapping #112

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
add T_QUICKTIME codec mappings
  • Loading branch information
dericed authored and robUx4 committed Mar 14, 2021

Verified

This commit was signed with the committer’s verified signature.
lukaszlenart Lukasz Lenart
commit a607eaf424866eff6f7479932dc941b511d119b4
23 changes: 23 additions & 0 deletions codec_specs.md
Original file line number Diff line number Diff line change
@@ -37,6 +37,7 @@ Video | "V_"
Audio | "A_"
Subtitle | "S_"
Button | "B_"
Timecode | "T_"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is currently no "timecode" track type. There is a "metadata" track type which seems to be fitting. So maybe the prefix should be "M_" and the type called Metadata ?

We can also add a "timecode" track type. In the end it's more informational for the player what this is about, although it should be able to tell what kind of metadata we're talking about just by looking at the codec. But at the container level (don't know what's in codecs) it might be usefull to tell if we have timecodes or not.


Each `Codec ID` **MUST** include a `Major Codec ID` immediately following the `Codec ID Prefix`.
A `Major Codec ID` **MAY** be followed by an **OPTIONAL** `Codec ID Suffix` to communicate a refinement
@@ -997,3 +998,25 @@ Block type name: MVC configuration

Description: the `BlockAddIDExtraData` data is interpreted as `MVCDecoderConfigurationRecord` structure, as defined in [@!ISO.14496-15].
This extension **MUST NOT** be used if `Codec ID` is not `V_MPEG4/ISO/AVC`.

## Timecode Codec Mappings

### T_QUICKTIME/SINGLE

Codec ID: T_QUICKTIME/SINGLE
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to tell what track type to use "metadata", "subtitle", "timecode" ? Maybe this should be explained in the chapter above.


Codec Name: QuickTime timecode track (continuous)

Description: `T_QUICKTIME/SINGLE` is used to identify Timecode tracks as stored in QuickTime. The `QuickTime Timecode Sample Data` is stored within the Block's data section. For an explanation of `QuickTime Timecode Sample Data` read [QuickTime File Format Specification](https://developer.apple.com/library/content/documentation/QuickTime/QTFF/QTFFChap3/qtff3.html#//apple_ref/doc/uid/TP40000939-CH205-57421). In the context of Matroska, `T_QUICKTIME/SINGLE` tracks MUST only relate to exactly one `Cluster` which MUST have a `Cluster Timecode` of zero and exactly one `SimpleBlock` or `BlockGroup Element`. The storage of the `QuickTime Timecode Sample Data` with the `SimpleBlock` or `BlockGroup Element` allows the `QuickTime Timecode` to be mapped to the `Matroska Timecode` at a single point. The `QuickTime Timecode` value MAY then be evaluated at any point in the `Matroska Timecode` by using the initialised `Timecode Sample Description`, the single `QuickTime Timecode Sample Data` value, and the `Matroska Timecode`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

British initialised or American initialized? The rest seems to me American.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two things I'd like to discuss:

In the context of Matroska, T_QUICKTIME/SINGLE tracks MUST only relate to exactly one Cluster which MUST have a Cluster Timecode of zero and exactly one SimpleBlock or BlockGroup Element.

I honestly don't understand what this is supposed to mean, especially the verb "relate". Do you mean to say that for a track with the CodecID T_QUICKTIME/SINGLE there MUST be exactly one BlockGroup or SimpleBlock, that this singular block is stored in a cluster with ClusterTimecode set to 0, and that there MUST NOT be any other cluster in the file with ClusterTimecode set to 0?

If yes, why such severe restrictions? Why not allow multiple Clusters that start at 0 (by simply omitting the restriction)? What about files whose first cluster doesn't start at 0 — how would that be interpreted? And why are you saying something about the Cluster Timecode but not about the timecode parts of the blocks?

In other words: can you please describe all of your thoughts in much more detail? We can then see how to turn that into unambiguous verbiage.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The second issue I have is with linking to other web pages as part of the format specification. I'd rather we refer to existing PDF documentation or publications. In the case of linking to the QuickTime specification this is both possible and a bit difficult: possible because there is a PDF version of the QuickTime specs, and harder because it doesn't contain numbered chapters and sections. I still prefer to say something like this:

For an explanation of the format read the section "Timecode Media", sub-section "Timecode Sample Description", of Apple's QuickTime File Format Specification (2001).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, I suggest that T_QUICKTIME/SINGLE implies that only a single Cluster is associated with that track. I didn't mean that imply that other tracks could not share the same timecode value. Upon reflection I think the requirement to use a Cluster Timecode is unnecessary. What is needed in T_QUICKTIME/SINGLE is for a single QuickTime Timecode Sample Data value to be stored in a single BlockGroup or SimpleBlock of a single Cluster, then the QuickTime Timecode Sample Data (within the Block) and the Timecode Sample Description (in Private Data) and the Cluster Timecode and the Block Timecode can be used to calculate what the QuickTime Timecode value should be relative to any Matroska Timecode value. Still for a Matroska Reader that needs to quickly associate any Matroska Timecode value with a QuickTime Timecode value it would be good to know where that Cluster is quickly. I had intended to have Cluster as 0 timecode to mean that it should be one of the first Clusters, but of course that is not a good expectation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If finding the (single) BlockGroup/SimpleBlock is the goal, then just say that the BlockGroup/SimpleBlock SHOULD be referenced via Cues.

I don't like requiring that the first or one of the first cluster contains that data as that seems problematic wrt streaming Matroska files.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any other Codec Mappings that require Cues?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

None that I know of.


Initialisation: The `Private Data` contains the `Timecode Sample Description` which in QuickTime is stored within the 'tmcd' atom after the mandatory `data reference index` value. For an explanation of the `Timecode Sample Description` read [QuickTime File Format Specification](https://developer.apple.com/library/content/documentation/QuickTime/QTFF/QTFFChap3/qtff3.html#//apple_ref/doc/uid/TP40000939-CH205-69831).
Copy link
Contributor

@retokromer retokromer Sep 17, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here (and below)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same issue with referencing web pages vs. a published standard (as a PDF).


### T_QUICKTIME/MULTIPLE

Codec ID: T_QUICKTIME/MULTIPLE

Codec Name: QuickTime timecode track (continuous)

Description: Same as defined in the `T_QUICKTIME/SINGLE` `Codec Mapping`, except that the `T_QUICKTIME/MULTIPLE` track MAY reference multiple `Clusters`. The `QuickTime Timecode` value MAY then be evaluated at any point in the `Matroska Timecode` by using the `Matroska Timecode`, the initialised `Timecode Sample Description`, the `QuickTime Timecode Sample Data` value of the `Cluster` which has the greatest `Timecode` which is equal to or lesser than the current `Matroska Timecode` value.

Initialisation: Same as defined in the `T_QUICKTIME/SINGLE` `Codec Mapping`.