Timing

Timing

Each track and scene has to have a defined or inferable duration. We provide multiple ways of defining these timing constraints. It is up to you to decide which way you would like to use.

Scene duration

You can set the duration of each scene in three different ways. In either case no matter how long the duration of the tracks within the scene are, everything longer than the scene itself will be cut out.

Explicit scene duration

You can explicitly define the scene's duration in milliseconds by setting the duration property on it.

const job = {
  videoCreative: {
    settings: {
      name: "Simple video with a single scene",
      videoSize: { height: 1080, width: 1920 },
    },
    scenes: [
      {
        name: "Scene with explicit duration",
        duration: 2000, // ms
        tracks: [
          {
            type: "actor",
            position: { x: 200, y: 200 }, // From the top left in pixels
            size: { height: 680, width: 1520 }, // In pixels
            text: "This scene is exactly two seconds long. It does not matter how long any of the tracks are.",
            speakerId: "en-GB-RyanNeural",
            actor: "ryan",
          },
        ],
      },
    ],
  },
};

Referring to a track

If you would like your scene to be exactly as long as one of the tracks in it, you can do so by referring to the track on the scene. In this case Colossyan will try to figure out the length of the track in isolation first, and if it can do so, it'll assign the same duration to the scene itself.

In this case the track duration can only be inferred if it has an default or an explicitly defined duration.

This is very handy when you would like to make sure that the scene will not end before an actor finishes speaking, or before the end of a video.

Use the intrinsicDurationTrackReference property in the scene to refer to the referenceId of the track you would like the scene to have an equal duration with.

const job = {
  videoCreative: {
    settings: {
      name: "Simple video with a single scene",
      videoSize: { height: 1080, width: 1920 },
    },
    scenes: [
      {
        name: "This scene lasts until the actor stops speaking",
        intrinsicDurationTrackReference: "speech",
        tracks: [
          {
            type: "actor",
            referenceId: "speech",
            position: { x: 200, y: 200 }, // From the top left in pixels
            size: { height: 680, width: 1520 }, // In pixels
            text: "It does not matter how long I am talking. The scene will last as long as necessary.",
            speakerId: "en-GB-RyanNeural",
            actor: "ryan",
          },
        ],
      },
    ],
  },
};

Combining this technique with timing the tracks by referring to the scene's start and end time is a very powerful combination, that allows you to achieve intricate videos with the flexibility of handing varying track lengths.

Default scene duration

If you do not explicitly set the duration, nor refer to a track within the scene, Colossyan will try to infer the best guess for the duration of the scene by looking at the tracks, and trying to find a single one with either an intrinsic or explicitly set duration.

This is only possible if there is only one track in the scene with a default or explicitly set duration. Otherwise Colossyan will throw a schema validation error, when queueing the job.

const job = {
  videoCreative: {
    settings: {
      name: "Simple video with a single scene",
      videoSize: { height: 1080, width: 1920 },
    },
    scenes: [
      {
        name: "This scene defaults to last until the end of the video",
        tracks: [
          {
            type: "video",
            position: { x: 200, y: 200 }, // From the top left in pixels
            size: { height: 680, width: 1520 }, // In pixels
            videoUrl: "https://your.cdn.com/public/videos/some_video.mp4",
          },
        ],
      },
    ],
  },
};

Track duration

Track duration can be set in three different ways. No matter which way you chose, if the scene is shorter, the track will be cut to fit it.

If however the track you provided does not last long enough to reach the duration defined by you (for example a video ends earlier, or the actor finishes speaking), the track will disappear earlier than you defined.

Explicit track duration

Similarly to setting a scene's explicit duration, you can set the duration of a track by setting the duration property on it. The duration should be set in milliseconds.

const job = {
  videoCreative: {
    settings: {
      name: "Simple video with a single scene",
      videoSize: { height: 1080, width: 1920 },
    },
    scenes: [
      {
        name: "Scene with a single track with an explicitly set duration",
        tracks: [
          {
            type: "image",
            duration: 3000, // in ms
            position: { x: 200, y: 200 }, // From the top left in pixels
            size: { height: 680, width: 1520 }, // In pixels
            imageUrl: "https://your.cdn.com/public/videos/image.jpg",
          },
        ],
      },
    ],
  },
};

Referring to the scene's start and end time

You can set the track to start after a certain amount of time has passed since the beginning of the scene, and to last until a certain amount of time before the end of the scene. By setting both of these variables, you are essentially defining the duration of the track as well.

You can define these gaps from the start and end of the scene by setting the startTimeGap and the endTimeGap properties on the track.

You can only time the track this way if the scene itself does not rely on the track's duration.

const job = {
  videoCreative: {
    settings: {
      name: "Simple video with a single scene",
      videoSize: { height: 1080, width: 1920 },
    },
    scenes: [
      {
        name: "Scene with a single track with a duration set by startTimeGap and endTimeGap",
        duration: 5000,
        tracks: [
          {
            type: "image",
            startTimeGap: 1000, // ms
            endTimeGap: 2000, // ms
            position: { x: 200, y: 200 }, // From the top left in pixels
            size: { height: 680, width: 1520 }, // In pixels
            imageUrl: "https://your.cdn.com/public/videos/image.jpg",
          },
        ],
      },
    ],
  },
};

Default track duration

If you do not define the duration of the track in any way, Colossyan will try to fall back to the intrinsic duration of the track if there is any.

Only video and actor tracks have intrinsic durations.

• In case of a video track the intrinsic duration equals the duration of the video itself.

• In case of an actor track the intrinsic duration equals the duration of the lipsynched video of the actor speaking.

const job = {
  videoCreative: {
    settings: {
      name: "Simple video with a single scene",
      videoSize: { height: 1080, width: 1920 },
    },
    scenes: [
      {
        name: "Scene with a single track with an intrinsic duration",
        tracks: [
          {
            type: "video",
            position: { x: 200, y: 200 }, // From the top left in pixels
            size: { height: 680, width: 1520 }, // In pixels
            imageUrl: "https://your.cdn.com/public/videos/some_video.mp4",
          },
        ],
      },
    ],
  },
};

Timing tracks within a scene

To time when the track should start or end within the scene, you can use the startTimeGap or the endTimeGap properties on the track.

If you find yourself in a situation where these options are not suitable for your use-case, double check if there is a way to subdivide your content to different scenes, to achieve the result you are looking for.

Good practices

• Use startTimeGap and endTimeGap to make videos that work well for dynamic content.

• Refer to the track's duration in scenes to deal with dynamic track lengths.

• Do not over-constrain the timing of your scenes and tracks. This will yield in a schema validation error.