DRAFT

Motivation

Time codes are an essential aspect when managing assets in an Enterprise MAM Solution. As assets and their technical and descriptive metadata are stored in VidiCore, the time code representation of VidiCore is the key concept.

Storing Time Codes In VidiCore

VidiCore always denoted time codes as a pair of a number and the corresponding unit: e.g. 90000@25 would be 90000 frames with 25 frames per second. For more details refer to VidiCore’s APIdoc.

It is important to understand that the unit (often described as frames per second) of a VidiCore time code does not (necessarily) relate to the sample rate of the corresponding video. This aligns with the data model found in many video container formats like MXF.

A video recorded with 25 frames per second starting a 10:00:00:00 may have a start time code of 900000@25 - in this case the time code’s unit aligns with the sample rate of the video. But it also may have a start time code of 1800000@50 or 36000@1 (i.e. 36000 seconds = 10 hours). All 3 values refer to the same point-in-time - and thus to the same frame.

Time Codes, Items, And Shapes

Assets are represented by items in VidiCore. As an item may have multiple shapes holding different physical representations of a video, it is important to have a look at how timecodes on items and shapes relate to each other.

Shapes

On shape level all technical metadata for a specific representation of a video (usually a video file) are stored. This includes timecodes and the most important fields can be found on the ContainerComponent:

<shape>
    <id>SHAPE-VX-12761</id>
    <created>2021-03-24T13:32:04.742Z</created>
    <essenceVersion>0</essenceVersion>
    <tag>original</tag>
    <mimeType>video/x-mxf-h264-pcm_s16le</mimeType>
    <containerComponent>
        <file>
            <id>FILE-VX-16129</id>
            <path>test_short_1.mxf</path>
            [...]
        </file>
        <id>COMPONENT-VX-58980</id>
        <metadata>
          [...]
        </metadata>
        <duration>
            <samples>53</samples>
            <timeBase>
                <numerator>1001</numerator>
                <denominator>30000</denominator>
            </timeBase>
        </duration>
        <format>mxf</format>
        <firstSMPTETimecode>00:00:08;01</firstSMPTETimecode>
        <startTimecode>241</startTimecode>
        <startTimestamp>
            <samples>0</samples>
            <timeBase>
                <numerator>1</numerator>
                <denominator>90000</denominator>
            </timeBase>
        </startTimestamp>
        <roundedTimeBase>30</roundedTimeBase>
        <dropFrame>true</dropFrame>
        <timeCodeTimeBase>
            <numerator>1001</numerator>
            <denominator>30000</denominator>
        </timeCodeTimeBase>
        [...]

These values should be used when obtaining time code information from a shape:

Do not use the values from the <metadata> key-value information. These are specific to the container format - whereas to values in the table above are uniform across different container formats.

Item

When attaching the first shape to an item this usually becomes the original shape of the item - which denotes to original, unmodified video file as initially imported to VidiCore.

Some metadata of the original shape are transferred to system-defined metadata fields on item level:

These metadata fields on item level are automatically populated by VidiCore when the original shape is created and cannot be modified via VidiCore’s API.

Time Codes In User Interfaces

When display time codes (and durations) in user interfaces it usually is not only sufficient but also advisable to use time code and duration information from the item. As all shapes on an item must refer to a representation of the same visual content, all shapes must start at the same position. Please note that the same position on the timeline may be expressed in different time bases.

Time Codes In Proxy Playback

Although proxy shapes have their own set of technical metadata and thus also their own start time code and duration, it’s not advisable to use the shape values for the proxy player in the UI. The reason for this is that not all proxy formats have time code information stored within the file.

Proxy files in MXF usually have a correct start time code, but mp4 files may not always have a valid start time code. The mp4 container format does not have a defined location for storing a start time coder. There is only an extension to mp4 defined by Apple for storing the start time code. VidiCore’s transcoder is storing the start time code in the proxy videos it created - but other proxy transcoders may not do so.

Therefore, it’s better to not rely on the start time code stored in the proxy file - and thus ignore the start time code on the proxy shape.