Import a Lottie Animation
Import animations in Lottie format into the authoring tool to use in your Alexa Presentation Language (APL) documents. Lottie is a JSON animation format that you can export from Adobe After Effects.
Import a Lottie animation
With the authoring tool, you can convert a JSON file in Lottie format to Alexa Vector Graphics (AVG) format. You can then use the resulting animated vector graphic in your document.
Prepare the animation to import
The authoring tool supports Lottie files that were created in Adobe After Effects with the Bodymovin plugin (version 5.7.5).
The authoring tool doesn't support all After Effects features. Make sure your animation doesn't use unsupported features. For details, see Supported features.
For details about exporting an animation to Lottie format, see How to Get Started Using Bodymovin and Lottie in After Effects.
Import the animation
To import a Lottie animation
- In the developer console, open the skill for which you want to create this document.
- In the left-hand navigation, click Multimodal Responses.
- Click Create with Authoring Tool.
- Click Upload
- Either drag your Lottie file to the Upload your Visual Response dialog box, or click Browse and locate the file to import.
- Click Upload.
- When prompted, click Convert.
- If the conversion completes without errors, the tool opens to a new APL document that displays the converted animation.
- If the conversion encountered any errors, the tool displays the a list of the unsupported features. Review the list and click Continue. To prevent these errors, make sure your After Effects animation doesn't use any of the features that aren't supported in Lottie or in the authoring tool. For the list of supported features, see Supported features.
Review the animation and edit your document
After the authoring tool converts your document, the tool displays the new document with your animation. The new document has the following:
- An Alexa Vector Graphic (AVG) called
myGraphic
. ThemyGraphic
AVG definition is an object in thegraphics
property of the document. The AVG contains all the data from the Lottie animation to draw and animate the graphic. For details about the AVG format, see Alexa Vector Graphics Format. - A
VectorGraphic
component inmainTemplate
that displays themyGraphic
AVG, so you can see the animation.
For example, the APL document might look like the following. Note that the AVG detail has been removed for brevity.
{
"type": "APL",
"version": "2024.2",
"mainTemplate": {
"parameters": [
"payload"
],
"items": {
"type": "VectorGraphic",
"source": "myGraphic",
"width": "100%",
"height": "100%",
"scale": "best-fit",
"align": "center",
"frame": "${(elapsedTime*0.06)%360}"
}
},
"graphics": {
"myGraphic": {
"type": "AVG",
"version": "1.1",
"width": 1280,
"height": 800,
"description": "Animate-Item",
"items": [],
"parameters": [
{
"name": "frame",
"value": 0
}
],
"resources": []
}
}
}
Review the animation that resulted from the Lottie file. For significant changes, edit the animation in After Effects, re-export as a Lottie file, and repeat the steps to convert the file to APL. Uploading the Lottie file always creates a new APL document. You can't import a Lottie file into an existing APL document.
Incorporate the animation into your design
After you're satisfied with the animation, edit the document to incorporate the animation into the overall design. For example, add a Container
to mainTemplate
and move the VectorGraphic
component into the container alongside other components.
You might want to change the name of the AVG from myGraphic
to something more meaningful. Use the JSON code view and change the name in both places:
- The name of the graphic assigned to the
graphics
property. - The
source
property for theVectorGraphic
component.
For more information about editing a document in the authoring tool, see Create and Edit an APL Document.
Example document with a Lottie animation
The following example shows an APL document that displays the AlexaBackground
, AlexaHeader
, Text
, and VectorGraphic
components. The VectorGraphic
component references a graphic created from a Lottie animation. In this example, the graphic was renamed from myGraphic
to towerOfBlocksAnimation
.
Move the Lottie animation to an external package
The JSON code for a Lottie animation can be large. To keep your visual responses smaller, you can move the code for the animation into a separate external package, and then import that package into your APL document with the import
property.
For details about creating and hosting an external package, see Host Layouts, Graphics, and Other Resources in an APL Package.
Supported features
The authoring tool supports Lottie files created in Adobe After Effects with the Bodymovin plugin (version 5.7.5).
The Lottie format doesn't support all After Effects features. Features not supported by Lottie are also not supported by the authoring tool and APL. For the list of After Effects features that Lottie supports, see Supported Features in the Lottie documentation.
The following table summarizes the Adobe After Effects features that the authoring tool converts to AVG.
After Effects feature | Supported for conversion? |
---|---|
Shape |
|
Ellipse |
Yes |
Rectangle |
Yes |
Rounded Rectangle |
Limited support: Doesn't support rounded corner addon layer. |
Polystar |
Yes |
Group |
Yes |
Repeater |
No |
Trim Path (individually) |
Limited support. Converted results might be off due to a frame rate difference between APL and Lottie. |
Trim Path (simultaneously) |
Limited support. Converted results might be off due to a frame rate difference between APL and Lottie. |
Fills |
|
Color |
Yes |
Opacity |
Yes |
Fill Rule |
No |
Radial Gradient |
Yes |
Linear Gradient |
Yes |
Strokes |
|
Color |
Yes |
Opacity |
Yes |
Width |
Yes |
Line Cap |
Yes |
Line Join |
Yes |
Miter Limit |
No |
Dashes |
Yes. Note that dashes might conflict with Trim Path. |
Gradient |
Limited support: Supports linear gradient only. |
Transforms |
|
Position |
Yes |
Position (separated X/Y) |
Yes |
Scale |
Yes |
Rotation |
Yes |
Anchor Point |
Yes |
Opacity |
Yes |
Parenting |
Yes |
Auto Orient |
No |
Skew |
No |
Interpolation |
No |
Linear Interpolation |
Yes |
Bezier Interpolation |
Yes |
Hold Interpolation |
No |
Spatial Bezier Interpolation |
Yes |
Rove Across Time |
No |
Masks |
|
Mask Path |
Yes |
Mask Opacity |
Yes |
Add |
No |
Subtract |
No |
Intersect |
No |
Lighten |
No |
Darken |
No |
Difference |
No |
Expansion |
No |
Feather |
No |
Mattes | |
Alpha Matte |
Yes |
Alpha Inverted Matte |
No |
Luma Matte |
No |
Luma Inverted Matte |
No |
Merge Paths | |
Merge |
No |
Add |
No |
Subtract |
No |
Intersect |
No |
Exclude Intersection |
No |
Layer Effects | |
Fill |
No |
Stroke |
No |
Tint |
No |
Tritone |
No |
Levels Individual Controls |
No |
Text | |
Glyphs |
No |
Fonts |
No |
Transform |
No |
Fill |
No |
Stroke |
No |
Tracking |
No |
Anchor point grouping |
No |
Text Path |
No |
Per-character 3D |
No |
Range selector (Units) |
No |
Range selector (Based on) |
No |
Range selector (Amount) |
No |
Range selector (Shape) |
No |
Range selector (Ease High) |
No |
Range selector (Ease Low) |
No |
Range selector (Randomize order) |
No |
Expression selector |
No |
Other |
|
Expressions |
No |
Images |
Yes |
Precomps |
Yes |
Time Stretch |
No |
Time remap |
No |
Markers |
No |
Get the Lottie converter source code
The Lottie converter source code is open source and available if you want to integrate it into a custom APL authoring tool. The GitHub repository is available at https://github.com/alexa/apl-translator-lottie.
Troubleshooting
Issue: Conversion complete with issues message
Symptoms
The authoring tool displays a message stating "Conversion Complete with Issues." The message lists unsupported After Effects features.
Try this
This issue means that the authoring tool could import the file, but the results might not be what you expect due to the unsupported features.
Note the list of unsupported features shown in the message. Click Continue to see the resulting animation without the unsupported features. If this isn't what you expect, return to Adobe After Effects, revise the animation to remove those features, and then export the animation to Lottie and try the import again.
For the list of supported features, see Supported features.
Issue: There were errors converting your Lottie file
Symptoms
The authoring tool displays a message stating "There were errors converting your Lottie file." The message lists unsupported After Effects features.
Try this
This error means that the authoring tool couldn't import the file at all due to unsupported features.
Note the list of unsupported features shown in the message. Click Cancel to exit the conversion, or Start Over to import a different file.
Issue: File type not supported error
Symptoms
The authoring tool displays a message stating "File type not supported. Please select an APL or Lottie .json file."
Try this
This error means that the authoring doesn't recognize the file as a Lottie file. Click Cancel, and then make sure you create your animation with Adobe After Effects, and then export it with the Bodymovin plugin.
Lottie files created in other ways might not work with APL.
Issue: Preview pane displays blank screen after a successful conversion
Symptoms
The authoring tool displays a message indicating that the conversion was successful. However, the preview pane in the authoring tool displays a blank, black viewport with no animation. The left-hand pane of the tools displays the expected AVG and VectorGraphic
code.
Try this
This situation might occur if the animation you imported contains text and images that use black as the color. The animation imported correctly, but isn't visible against the default black viewport background.
Either change the background color for the document, or change to the light
theme to see the black animation.
The following examples show how you can change the background color or theme. Details are removed from the imported AVG (myGraphic
) for brevity.
Change the viewport theme
Add the document-level theme
property to the top level of the document and set it to light
.
{
"type": "APL",
"theme": "light",
"version": "2024.2",
"mainTemplate": {
"parameters": [
"payload"
],
"items": {
"type": "VectorGraphic",
"source": "myGraphic",
"width": "100%",
"height": "100%",
"scale": "best-fit",
"align": "center",
"frame": "${(elapsedTime*0.06)%1198}"
}
},
"graphics": {
"myGraphic": {}
}
}
Change the document background to a different color
Add the document-level background
property and set it to a color or gradient.
{
"type": "APL",
"version": "2024.2",
"background": "yellow",
"mainTemplate": {
"parameters": [
"payload"
],
"items": {
"type": "VectorGraphic",
"source": "myGraphic",
"width": "100%",
"height": "100%",
"scale": "best-fit",
"align": "center",
"frame": "${(elapsedTime*0.06)%1198}"
}
},
"graphics": {
"myGraphic": {}
}
}
Use the AlexaBackground responsive component
The AlexaBackground
component in the alexa-layouts
package gives you more control over the background. You can use a color, gradient, image, video, or default Alexa background. Because mainTemplate
displays a single component, you must add a Container
and move the AlexaBackground
and VectorGraphic
components into the items
array for the Container
.
To access the AlexaBackground
component, add the current version of alexa-layouts
to the import
array.
The following example shows how to import the alexa-layouts
package, and then how to arrange AlexaBackground
and VectorGraphic
in a Container
. This example uses the default Alexa background.
{
"type": "APL",
"version": "2024.2",
"import": [
{
"name": "alexa-layouts",
"version": "1.7.0"
}
],
"mainTemplate": {
"parameters": [
"payload"
],
"items": {
"type": "Container",
"width": "100%",
"height": "100%",
"items": [
{
"type": "AlexaBackground"
},
{
"type": "VectorGraphic",
"source": "myGraphic",
"width": "100%",
"height": "100%",
"scale": "best-fit",
"align": "center",
"frame": "${(elapsedTime*0.06)%1198}"
}
]
}
},
"graphics": {
"myGraphic": {}
}
}
For more about using backgrounds in APL, see Combine Content with Backgrounds, Borders, and Headers.
Related topics
- Build Documents in the Developer Console
- Create and Edit an APL Document
- Preview an APL Document
- Alexa Vector Graphics Format
- VectorGraphic
Other resources:
Last updated: Mar 11, 2024