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

1. In the developer console, open the skill for which you want to create this document.
2. In the left-hand navigation, click Multimodal Responses.
3. Click Create with Authoring Tool.
4. Click Upload
5. Either drag your Lottie file to the Upload your Visual Response dialog box, or click Browse and locate the file to import.
6. Click Upload.
7. 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. The myGraphic AVG definition is an object in the graphics 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 in mainTemplate that displays the myGraphic 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.3",
  "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 the VectorGraphic 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.

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.3",
  "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.3",
  "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.3",
  "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:

• Lottie format
• Bodymovin plugin
• Adobe After Effects

Last updated: Mar 11, 2024