How to Use Animations

CreativeEditor SDK supports many different types of configurable animations for animating the appearance of design blocks in video scenes.

Similarly to blocks, each animation object has a numeric id which can be used to query and modify its properties.

Explore a full code sample on Stackblitz or view the code on Github.

Setup#

This example uses the headless CreativeEngine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

Accessing Animation APIs#

In order to query whether a block supports animations, you should call the supportsAnimation(id: number): boolean API.

Animation Categories#

There are three different categories of animations: In, Out and Loop animations.

In Animations#

In animations animate a block for a specified duration after the block first appears in the scene. For example, if a block has a time offset of 4s in the scene and it has an In animation with a duration of 1s, then the appearance of the block will be animated between 4s and 5s with the In animation.

Out Animations#

Out animations animate a block for a specified duration before the block disappears from the scene. For example, if a block has a time offset of 4s in the scene and a duration of 5s and it has an Out animation with a duration of 1s, then the appearance of the block will be animated between 8s and 9s with the Out animation.

Loop Animations#

Loop animations animate a block for the total duration that the block is visible in the scene. Loop animations also run simultaneously with In and Out animations, if those are present.

Creating Animations#

In order to create a new animation, we must call the createAnimation(type: string): number API.

We currently support the following In and Out animation types:

'//ly.img.ubq/animation/slide'
'//ly.img.ubq/animation/pan'
'//ly.img.ubq/animation/fade'
'//ly.img.ubq/animation/blur'
'//ly.img.ubq/animation/grow'
'//ly.img.ubq/animation/zoom'
'//ly.img.ubq/animation/pop'
'//ly.img.ubq/animation/wipe'
'//ly.img.ubq/animation/baseline'
'//ly.img.ubq/animation/crop_zoom'
'//ly.img.ubq/animation/spin'
'//ly.img.ubq/animation/typewriter_text' (text-only)
'//ly.img.ubq/animation/block_swipe_text' (text-only)
'//ly.img.ubq/animation/merge_text' (text-only)
'//ly.img.ubq/animation/spread_text' (text-only)

and the following Loop animation types:

'//ly.img.ubq/animation/spin_loop'
'//ly.img.ubq/animation/fade_loop'
'//ly.img.ubq/animation/blur_loop'
'//ly.img.ubq/animation/pulsating_loop'
'//ly.img.ubq/animation/breathing_loop'
'//ly.img.ubq/animation/jump_loop'
'//ly.img.ubq/animation/squeeze_loop'
'//ly.img.ubq/animation/sway_loop'

Note: short types are also accepted, e.g. 'slide' instead of '//ly.img.ubq/animation/slide'.

Assigning Animations#

In order to assign an In animation to the block, call the setInAnimation(id: number, animation: number): void API.

In order to assign a Loop animation to the block, call the setLoopAnimation(id: number, animation: number): void API.

In order to assign an Out animation to the block, call the setOutAnimation(id: number, animation: number): void API.

To query the current animation ids of a design block, call the getInAnimation(id: number): number, getLoopAnimation(id: number): number or getOutAnimation(id: number): number API. You can now pass this id into other APIs in order to query more information about the animation, e.g. its type via the getType(id: number): string API.

When replacing the animation of a design block, remember to destroy the previous animation object if you don't intend to use it any further. Animation objects that are not attached to a design block will never be automatically destroyed.

Destroying a design block will also destroy all of its attached animations.

Animation Properties#

Just like design blocks, animations with different types have different properties that you can query and modify via the API. Use findAllProperties(id: number): string[] in order to get a list of all properties of a given animation.

For the slide animation in this example, the call would return ['name', 'animation/slide/direction', 'animationEasing', 'includedInExport', 'playback/duration', 'type', 'uuid'].

Please refer to the API docs for a complete list of all available properties for each type of animation.

Once we know the property keys of an animation, we can use the same APIs as for design blocks in order to modify those properties. For example, we can use setFloat(id: number, property: string, value: number): void in order to change the direction of the slide animation to make our block slide in from the top.

All animations have a duration. For In and Out animations, the duration defines the total length of the animation as described above. For Loop animations, the duration defines the length of each loop cycle.

We can use the setDuration(id: number, value: number): void API in order to change the animation duration.

Note that changing the duration of an In animation will automatically adjust the duration of the Out animation (and vice versa) in order to avoid overlaps between the two animations.

Some animations allow you to configure their easing behavior by choosing from a list of common easing curves. The easing controls the acceleration throughout the animation.

We can use the setEnum(id: number, value: number): void API in order to change the easing curve. Call engine.block.getEnumValues('animationEasing') in order to get a list of currently supported easing options.

In this example, we set the easing to EaseOut so that the animation starts fast and then slows down towards the end. An EaseIn easing would start slow and then speed up, while EaseInOut starts slow, speeds up towards the middle of the animation and then slows down towards the end again.

Text Animation Properties#

When applied to text blocks, some animations allow you to control whether the animation should be applied to the entire text at once, line by line, word by word or character by character.

We can use the setEnum(id: number, value: number): void API in order to change the text writing style. Call engine.block.getEnumValues('textAnimationWritingStyle') in order to get a list of currently supported text writing style options. The default writing style is Line.

In this example, we set the easing to Word so that the text animates in one word at a time.

Together with the writing style, you can also configure the overlap between the individual segments of a text animation using the textAnimationOverlap property.

With an overlap value of 0, the next segment only starts its animation once the previous segment's animation has finished. With an overlap value of 1, all segments animate at the same time.


import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.41.1/index.js';

const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.33.0/assets'
};

CreativeEngine.init(config).then(async (engine) => {
  document.getElementById('cesdk_container').append(engine.element);

  const scene = engine.scene.createVideo();
  const page = engine.block.create('page');
  engine.block.setWidth(page, 1920);
  engine.block.setHeight(page, 1080);
  engine.block.appendChild(scene, page);

  engine.editor.setSettingColor('clearColor', { r: 0.2, g: 0.2, b: 0.2, a: 1 });

  const graphic = engine.block.create('graphic');
  const imageFill = engine.block.createFill('image');
  engine.block.setString(
    imageFill,
    'fill/image/imageFileURI',
    'https://cdn.img.ly/assets/v3/ly.img.sticker/images/emoticons/imgly_sticker_emoticons_star.svg'
  );
  engine.block.setFill(graphic, imageFill);
  engine.block.setShape(graphic, engine.block.createShape('rect'));
  engine.block.setWidth(graphic, 500);
  engine.block.setHeight(graphic, 500);
  engine.block.setPositionX(graphic, (1920 - 500) / 2);
  engine.block.setPositionY(graphic, (1080 - 500) / 2);
  engine.block.appendChild(page, graphic);

  engine.scene.zoomToBlock(page, 60, 60, 60, 60);

  if (!engine.block.supportsAnimation(graphic)) {
    return;
  }

  const slideInAnimation = engine.block.createAnimation('slide');
  const breathingLoopAnimation = engine.block.createAnimation('breathing_loop');
  const fadeOutAnimation = engine.block.createAnimation('fade');
  engine.block.setInAnimation(graphic, slideInAnimation);
  engine.block.setLoopAnimation(graphic, breathingLoopAnimation);
  // highlight-setOutAnimation
  engine.block.setOutAnimation(graphic, fadeOutAnimation);
  // highlight-setOutAnimation
  const animation = engine.block.getLoopAnimation(graphic);
  const animationType = engine.block.getType(animation);

  const squeezeLoopAnimation = engine.block.createAnimation('squeeze_loop');
  engine.block.destroy(engine.block.getLoopAnimation(graphic));
  engine.block.setLoopAnimation(graphic, squeezeLoopAnimation);
  /* The following line would also destroy all currently attached animations */
  // engine.block.destroy(graphic);

  const allAnimationProperties = engine.block.findAllProperties(slideInAnimation);
  engine.block.setFloat(slideInAnimation, 'animation/slide/direction', 0.5 * Math.PI);
  engine.block.setDuration(slideInAnimation, 0.6);
  engine.block.setEnum(slideInAnimation, 'animationEasing', 'EaseOut');
  console.log("Available easing options:", engine.block.getEnumValues('animationEasing'));

  const text = engine.block.create('text');
  const textAnimation = engine.block.createAnimation('baseline');
  engine.block.setInAnimation(text, textAnimation);
  engine.block.appendChild(page, text);
  engine.block.setPositionX(text, 100);
  engine.block.setPositionY(text, 100);
  engine.block.setWidthMode(text, 'Auto');
  engine.block.setHeightMode(text, 'Auto');
  engine.block.replaceText(text, "You can animate text\nline by line,\nword by word,\nor character by character\nwith CE.SDK");
  engine.block.setEnum(textAnimation, 'textAnimationWritingStyle', 'Word');
  engine.block.setDuration(textAnimation, 2.0);
  engine.block.setEnum(textAnimation, 'animationEasing', 'EaseOut');

  const text2 = engine.block.create('text');
  const textAnimation2 = engine.block.createAnimation('pan');
  engine.block.setInAnimation(text2, textAnimation2);
  engine.block.appendChild(page, text2);
  engine.block.setPositionX(text2, 100);
  engine.block.setPositionY(text2, 500);
  engine.block.setWidth(text2, 500);
  engine.block.setHeightMode(text2, 'Auto');
  engine.block.replaceText(text2, "You can use the textAnimationOverlap property to control the overlap between text animation segments.");
  engine.block.setFloat(textAnimation2, 'textAnimationOverlap', 0.4);
  engine.block.setDuration(textAnimation2, 1.0);
  engine.block.setEnum(textAnimation2, 'animationEasing', 'EaseOut');

  engine.block.setPlaying(page, true);
  engine.block.setLooping(page, true);
});