Time Remap - Node.js | IMG.LY Docs

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

6 mins

estimated time

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.

import CreativeEngine from '@cesdk/node';
import { writeFileSync, mkdirSync } from 'fs';
import { config } from 'dotenv';

// Load environment variables
config();

/**
 * CE.SDK Server Guide: Time Remap Guide
 *
 * Demonstrates how a composition group remaps the clock of its children:
 * - Freezing the children with a static remap
 * - Playing them in reverse with a remap track
 * - Playing them forward and back with an eased track
 * - Reading the remap back and the error for blocks without a remap
 */
async function main() {
  // Initialize the headless Creative Engine
  const engine = await CreativeEngine.init({
    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
    // license: process.env.CESDK_LICENSE
  });

  try {
    // Create a scene with a 5 second page
    const scene = engine.scene.create('DepthStack');
    const page = engine.block.create('page');
    engine.block.setWidth(page, 1920);
    engine.block.setHeight(page, 1080);
    engine.block.appendChild(scene, page);
    engine.block.setDuration(page, 5);

    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

    // 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);

    // 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 } }
    ]);

    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 } }
    ]);

    // 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

    try {
      // Only a group has a time remap
      const ball = engine.block.getChildren(normal)[1];
      engine.block.setFloat(ball, 'playback/timeRemap', 1);
    } catch (error) {
      // Engine errors carry a stable catalog id in `code`
      const { code } = error as { code?: string };
      console.log(code); // 'EDITOR.BLOCK_NO_TIME_REMAP_SUPPORT'
    }

    // Export the frame at 1.5 seconds
    engine.block.setPlaybackTime(page, 1.5);
    mkdirSync('output', { recursive: true });
    const blob = await engine.block.export(page, { mimeType: 'image/png' });
    writeFileSync(
      'output/time-remap.png',
      Buffer.from(await blob.arrayBuffer())
    );
    console.log('Frame saved to output/time-remap.png');
  } finally {
    // Always dispose of the engine to free resources
    engine.dispose();
  }
}

/**
 * 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;
}

main().catch(console.error);

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. It ends with a frame export.

Creating the Scene#

We start the headless engine and create a scene with a page of 5 seconds.

// Initialize the headless Creative Engine
const engine = await CreativeEngine.init({
  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
  // license: process.env.CESDK_LICENSE
});

try {
  // Create a scene with a 5 second page
  const scene = engine.scene.create('DepthStack');
  const page = engine.block.create('page');
  engine.block.setWidth(page, 1920);
  engine.block.setHeight(page, 1080);
  engine.block.appendChild(scene, page);
  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) {
  // Engine errors carry a stable catalog id in `code`
  const { code } = error as { code?: string };
  console.log(code); // 'EDITOR.BLOCK_NO_TIME_REMAP_SUPPORT'
}

Exporting a Frame#

We export the page as PNG at 1.5 seconds. The gray ball is at 30 percent of its lane, the blue ball in the middle, the red ball at 70 percent, and the green ball past the middle on its way out.

// Export the frame at 1.5 seconds
engine.block.setPlaybackTime(page, 1.5);
mkdirSync('output', { recursive: true });
const blob = await engine.block.export(page, { mimeType: 'image/png' });
writeFileSync(
  'output/time-remap.png',
  Buffer.from(await blob.arrayBuffer())
);
console.log('Frame saved to output/time-remap.png');

Cleaning Up#

We dispose of the engine in a finally block, so it frees its resources also after an error.

// Always dispose of the engine to free resources
engine.dispose();

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
`block.export(block, options)`	Export the frame as PNG

Next Steps#

Keyframes: easing and the other keyframe value kinds.
Create Animations: add preset animations to blocks.