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 time code refers to specific position on the timeline of a video - not to a specific frame of the video.

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>
        [...]
CODE

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

Shape Element

Format

Meaning

shape.containerComponent.startTimecode

integer number

The start time code of the shape as an integer. The unit is denoted by shape.containerComponent.timeCodeTimeBase

shape.containerComponent.timeCodeTimeBase

length of a unit in seconds, denoted as fraction (numerator=1 and denominator=25 means: each unit is 1/25s long, i.e. 25 fps)

The unit for the number in shape.containerComponent.startTimecode

shape.containerComponent.roundeTimeBase

integer number

The unit from shape.containerComponent.startTimecode as a rounded integer.

shape.containerComponent.duration

sample count (integer) + time base (length of one unit fraction)

The duration of the video

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:

Metadata Field

Format

Meaning

startTimeCode

VidiCore time code

The start time code of the video - corresponds to the start time code of the original shape.

startSeconds

integer number

The start time code of the video expressed as seconds (rounded).

durationTimeCode

VidiCore time code

The duration of the video as time code - corresponds to the duration element of the original shape.

durationSeconds

integer number

The duration of the video expressed as seconds (rounded).

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.

Time Codes For Camera Material

Camera material originating from professional cameras like Sony XDCAM or Panasonic P2 need special consideration as each clip on the camera usually has it distinct start time code. Please refer to Original Timecodes [GL ARC] for more details.