Search Docs
Loading...
Skip to content

Time Remap

Freeze, reverse or replay the children of a composition group by remapping their clock.

Four lanes of the same moving ball: normal, frozen, reversed and forward and back, at 1.5 seconds

6 mins
estimated time
Download
StackBlitz
GitHub

A composition group gives its children their own clock. playback/timeRemap sets the time on that clock, in seconds, that the children show. A static value freezes them, and 'Float' keyframes drive them over the group’s duration. The editor has no time remap controls, so you set them with the block API.

This guide covers how to turn time remap on, how to freeze the children, how to play them in reverse or forward and back, how to read the remap back, and the error to expect.

Creating the Scene#

We create a video scene with a page of 5 seconds.

await cesdk.actions.run('scene.create', {
  mode: 'Video',
  layout: 'DepthStack',
  page: { width: 1920, height: 1080, unit: 'Pixel' }
});


const engine = cesdk.engine;
const page = engine.block.findByType('page')[0]!;
engine.block.setDuration(page, 5);

Creating a Composition Group#

Time remap acts on the children of a composition group. Each lane of the example is a group with a gray line and a ball. The ball has a position/x track and crosses the page in 5 seconds of the group’s clock. group() groups the two blocks, and group/composition gives the group its own clock for its children.

/**
 * Creates a lane: a composition group with a line and a ball that crosses
 * the page in 5 seconds of the group's own clock.
 */
function createLane(
  engine: CreativeEngine,
  page: number,
  y: number,
  color: { r: number; g: number; b: number; a: number }
): number {
  const line = engine.block.create('graphic');
  engine.block.setShape(line, engine.block.createShape('rect'));
  const lineFill = engine.block.createFill('color');
  engine.block.setColor(lineFill, 'fill/color/value', {
    r: 0.85,
    g: 0.85,
    b: 0.85,
    a: 1
  });
  engine.block.setFill(line, lineFill);
  engine.block.setWidth(line, 1680);
  engine.block.setHeight(line, 6);
  engine.block.setPositionX(line, 120);
  engine.block.setPositionY(line, y + 37);
  engine.block.appendChild(page, line);
  engine.block.setDuration(line, 5);


  const ball = engine.block.create('graphic');
  engine.block.setShape(ball, engine.block.createShape('ellipse'));
  const ballFill = engine.block.createFill('color');
  engine.block.setColor(ballFill, 'fill/color/value', color);
  engine.block.setFill(ball, ballFill);
  engine.block.setWidth(ball, 80);
  engine.block.setHeight(ball, 80);
  engine.block.setPositionY(ball, y);
  engine.block.appendChild(page, ball);
  engine.block.setDuration(ball, 5);
  engine.block.setKeyframes(ball, 'position/x', [
    { time: 0, value: { type: 'Float', value: 120 } },
    { time: 1, value: { type: 'Float', value: 1720 } }
  ]);


  const lane = engine.block.group([line, ball]);
  engine.block.setDuration(lane, 5);
  // A composition group gives its children their own clock
  engine.block.setBool(lane, 'group/composition', true);
  return lane;
}

Creating the Lanes#

The example creates four lanes. The first one plays normally, and the other three get a time remap below. playback/timeRemapEnabled is off by default, and getBool() reads it.

const normal = createLane(engine, page, 150, {
  r: 0.6,
  g: 0.6,
  b: 0.6,
  a: 1
});
const frozen = createLane(engine, page, 400, {
  r: 0.2,
  g: 0.4,
  b: 0.9,
  a: 1
});
const reversed = createLane(engine, page, 650, {
  r: 0.9,
  g: 0.3,
  b: 0.4,
  a: 1
});
const pingPong = createLane(engine, page, 900, {
  r: 0.2,
  g: 0.7,
  b: 0.3,
  a: 1
});
console.log(engine.block.getBool(normal, 'playback/timeRemapEnabled')); // false

Freezing the Children#

setBool() turns on playback/timeRemapEnabled. A static playback/timeRemap, set with setFloat(), then holds the children at that time on their clock, here 2.5 seconds, so the blue ball stays in the middle of its lane.

// A static remap holds the children at 2.5 seconds of their own time
engine.block.setBool(frozen, 'playback/timeRemapEnabled', true);
engine.block.setFloat(frozen, 'playback/timeRemap', 2.5);

Playing in Reverse#

A track on playback/timeRemap drives the children while the group plays. The keyframe times are normalized over the group’s duration, from 0 to 1. The values are times on the children’s clock, in seconds. The track from just below 5 to 0 plays the red ball from the end of its lane back to the start. The values stay below 5, because a child shows only while the clock is before its end.

// The track values are times on the children's clock, in seconds. They
// stay below 5, because a clock at a child's end hides the child.
engine.block.setBool(reversed, 'playback/timeRemapEnabled', true);
engine.block.setKeyframes(reversed, 'playback/timeRemap', [
  { time: 0, value: { type: 'Float', value: 4.99 } },
  { time: 1, value: { type: 'Float', value: 0 } }
]);

Playing Forward and Back#

Three keyframes play the children forward to just below 5 seconds and back to 0. The 'EaseInOut' easing slows the green ball at both ends and at the turn.

engine.block.setBool(pingPong, 'playback/timeRemapEnabled', true);
engine.block.setKeyframes(pingPong, 'playback/timeRemap', [
  {
    time: 0,
    value: { type: 'Float', value: 0 },
    easing: { type: 'Preset', preset: 'EaseInOut' }
  },
  {
    time: 0.5,
    value: { type: 'Float', value: 4.99 },
    easing: { type: 'Preset', preset: 'EaseInOut' }
  },
  { time: 1, value: { type: 'Float', value: 0 } }
]);

Reading the Remap Back#

A track leaves the static value of playback/timeRemap unchanged, so getFloat() still reads 0 for the reversed lane. isPropertyAnimatable() is true for playback/timeRemap on a group and false on other blocks.

// The track leaves the static remap unchanged
console.log(engine.block.getFloat(reversed, 'playback/timeRemap')); // 0
console.log(
  engine.block.isPropertyAnimatable(reversed, 'playback/timeRemap')
); // true

Handling Errors#

Only a group has a time remap. On any other block, a call throws an error with a code.

try {
  // Only a group has a time remap
  const ball = engine.block.getChildren(normal)[1];
  engine.block.setFloat(ball, 'playback/timeRemap', 1);
} catch (error) {
  if (isEngineError(error)) {
    console.log(error.code); // 'EDITOR.BLOCK_NO_TIME_REMAP_SUPPORT'
  }
}

Time Remap and Other Block Operations#

  • Without group/composition, the remap has no effect, and the children play on the page clock.
  • playback/speed of a composition group multiplies the remapped time.
  • A child shows only while the remapped time is at or after its time offset and before its end, so a clock at a child’s end, or a reversed or frozen clock, can hide it.
  • A 'Relative' remap track adds its values to the static remap.
  • Saving and loading, undo and redo keep the remap and its keyframes.

Troubleshooting#

  • The block has no time remap (EDITOR.BLOCK_NO_TIME_REMAP_SUPPORT): set playback/timeRemap on a group.
  • The block takes no remap keyframes (BLOCK.KEYFRAMES_PROPERTY_NOT_ANIMATABLE): set playback/timeRemap keyframes on a group.
  • The value is not a number (BLOCK.VALUE_NOT_FINITE): pass a finite time in seconds.
  • The keyframes are refused (BLOCK.KEYFRAMES_VALUE_KIND_MISMATCH): use 'Float' keyframes for playback/timeRemap.
  • The children do not change: turn on group/composition and playback/timeRemapEnabled for the group.
  • A child disappears: the remapped time is outside the child’s time offset and duration.

API Reference#

Method Description
block.group(ids) Group blocks into a group
block.setBool(group, property, value) Turn on group/composition or playback/timeRemapEnabled
block.getBool(group, 'playback/timeRemapEnabled') Check whether the remap is on
block.setFloat(group, 'playback/timeRemap', value) Set the static remap, in seconds
block.getFloat(group, 'playback/timeRemap') Read the static remap
block.setKeyframes(group, 'playback/timeRemap', keyframes) Animate the remap
block.isPropertyAnimatable(block, 'playback/timeRemap') Check that a block takes remap keyframes
block.getChildren(group) Get the children of a group
block.setPlaybackTime(block, time) Show a frame at a playback time

Next Steps#