Creating a Simple Gateway Clip

Solution

Use the simplest form of .clip you can create: one video track, no audio. The following is the minimal structure required to to have a valid Gateway clip.

<?xml version="1.0" encoding="UTF-8"?>
<clip type="clip" version=3>
    <tracks>
        <track uid="client-defined unique identifier">
            <trackType>video</trackType>
            <feeds currentVersion="the <feed> vuid">
                <feed  vuid="client defined" uid="client-defined unique identifier">
                    <spans>
                        <span>
                            <duration>number of samples in the media sequence</duration>
                            <path>path the media sequence</path>
                        </span>
                    </spans>
                </feed>
            </feeds>
        </track>
    </tracks>
    <versions currentVersion="one of the <version> uid">
        <version uid="the currentVersion of <feeds>"/>
    </versions
</clip>

NoteRegarding files sequence and padding in the <path> element: The Gateway reconstructs a sequence as indicated by brackets. dpxSequence.[1-99].dpx indicates to the Gateway there are 99 dpx files named dpxSequence.1.dpx to dpxSequence.99.dpx. It can also manage padding. dpxSequence.[001-099].dpx is read as a sequence of 99 files named dpxSequence.001.dpx to dpxSequence.099.dpx.

Example and Discussion

Here is a commented .clip file. It does contain additional elements than the bare minimum, so as to play nicely with Smoke, Flame, or Lustre applications.

<?xml version="1.0" encoding="UTF-8"?>
<clip type="clip" version=3>
    <name type="string">NoVersionNoSetup</name>
    <tracks>
        <track uid="1b22da75-33e5-4dbe-80d0-7ed680a8b2b7">
            <trackType>video</trackType>
            <duration type="time">
                <rate type="rate">
                    <numerator>30000</numerator>
                    <denominator>1001</denominator>
                </rate>
                <nbTicks>26</nbTicks>
                <dropMode>NDF</dropMode>
            </duration>
            <name type="string">ClipNoVersionNoSetup</name>
            <feeds currentVersion="0">
                <feed vuid="0" uid="track1Feed1">
                    <spans>
                        <span>
                            <duration>26</duration>
                            <path>/var/tmp/UltimateFlick.[001-026].dpx</path>
                        </span>
                    </spans>
                </feed>
            </feeds>
        </track>
    </tracks>
    <versions currentVersion="0">
        <version uid="0">
            <creationDate>2010/12/14 11:54:06</creationDate>
        </version>
    </versions>
</clip>

NoteIf you compare this to the .clip structure described before, you will notice the use of user-defined elements such as <userData>. Both are optional. For example, Flame uses the following child of <clip>:

<userData type="dict">
    <appName type="string">Flame</appName>
    <appVersion type="string">2012</appVersion>
</userData>

This is used by Flame to determine the software and version used to create the .clip. But the Gateway ignores all <userData>: it is up to the client application to determine what to do with it.

Comments

<clip type="clip" version=3>

The <clip> element has two required attributes, with fixed values: type="clip" and version=3.

<name type="string">NoVersionNoSetup</name>

<name> is optional, but the client application uses it as the name of the clip. Note here that type="string" is mandatory so that the Gateway knows how to pass it to the client application.

<track uid="1b22da75-33e5-4dbe-80d0-7ed680a8b2b7">

Since this example has only one video track (or layer), there is only one <track> element.

The uid used here is a UUID, but it can be something as simple as "1", as long as it is unique accross <track> elements.

<trackType>video</trackType>

video is one of two allowed values in the <trackType> context, the other being audio. You must have a defined <trackType> for each <track>.

<duration type="time">
    <rate type="rate">
        <numerator>30000</numerator>
        <denominator>1001</denominator>
    </rate>
    <nbTicks>26</nbTicks>
    <dropMode>NDF</dropMode>
</duration>

<duration> defines the duration of the track, using the formula <rate>/<nbTicks>.

The <rate> element used here is the best definition of the 29.97 fps frame rate. This avoids rounding errors. Of course, if the frame rate is an integer such as 24 fps, use the simplified structure <rate>24</rate>.

And since 29.97 fps can be drop frame or non-drop frame, we have to define <dropMode>.

<name type="string">ClipNoVersionNoSetup</name>

Again, <name> is optional here, but Flame uses it as the name of the track.

<feeds currentVersion="0">

currentVersion refers to the vuid of the enclosed <feed>.

<feed vuid="0" uid="track1Feed1">

A feed forms a version of a track, identified with by its vuid.

As shown here (track1Feed1), a <feed uid=> can be any sort of value, as long as it is unique across all the <feed> elements.

<spans>

The <spans> element exists because you can have multiple spans. Such is the case with media cartridges that split clips into 2GB files.

<span>
    <duration>26</duration>
    <path>/var/tmp/UltimateFlick.[001-026].dpx</path>
</span>

Because we have 26 dpx files, and because we want to use them all, <duration> is set at 26. To use less of it, we can specify a lower value.

When linking to streaming media, <duration> becomes the number of samples to use.

<versions currentVersion="0">
    <version uid="0">
        <creationDate>2010/12/14 11:54:06</creationDate>
    </version>
    </versions>
</clip>

Every .clip has at least one version, defined using a <version> element. currentVersion refers to an existing uid from a <version>. The uid must be an existing vuid.

<creationDate> is not parsed by the Gateway, only passed to the client application.