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'
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.