Lottie Python

0.7.2 verified Fri May 01 auth: no python

A framework to work with Lottie files (Bodymovin JSON animations) and Telegram animated stickers (TGS format). Current version 0.7.2, supports Python >=3. Maintenance mode; no frequent releases.

pip install lottie

Common errors

error ImportError: cannot import name 'export_tgs' from 'lottie' ↓

cause export_tgs is in a submodule, not top-level.

fix

Use: from lottie.exporters.tgs import export_tgs

error AttributeError: module 'lottie' has no attribute 'NVector' ↓

cause NVector is not directly exposed.

fix

Use: from lottie.objects.base import NVector

error ValueError: Color values must be in range [0,1] ↓

cause Using 0-255 integer values for Color.

fix

Divide each value by 255: Color(r/255, g/255, b/255).

error TypeError: __init__() got an unexpected keyword argument 'position' ↓

cause Older API used 'position' as argument; now set as attribute.

fix

Create instance then assign: shape.position = objects.Point(...)

Warnings

deprecated The old `lottie.parsers` API is deprecated; use `lottie.importers` instead. ↓

fix Replace import from lottie.parsers with lottie.importers.

gotcha All coordinates and sizes are normalised 0-1, not pixel values. Using raw pixel values will result in invisible or off-screen elements. ↓

fix Divide pixel values by canvas dimensions to get normalised coordinates.

gotcha `objects.Color` expects normalised RGB float (0-1), not 0-255 integers. Using 0-255 will produce washed-out colors. ↓

fix Divide RGB values by 255 when constructing Color.

breaking In version 0.7.0, the `NVector` class signature changed from (x,y) to (x,y,z) with z optional. Code using positional arguments may break. ↓

fix Update NVector calls to include z=0 explicitly if needed.

Imports

lottie
wrong
```
from lottie import *
```
correct
```
import lottie
```
Common mistake: wildcard import clutters namespace

NVector

wrong

from lottie import NVector

correct

from lottie.objects.base import NVector

NVector is not in top-level module

Player

wrong

from lottie import Player

correct

from lottie.player import Player

Player class moved to submodule in 0.7

export_tgs

wrong

from lottie import export_tgs

correct

from lottie.exporters.tgs import export_tgs

export_tgs function not directly exposed

Color

wrong

from lottie import Color

correct

from lottie.objects.base import Color

Color not in top-level module

Quickstart

Create a simple red circle animation and export as TGS.

import lottie
from lottie import objects
from lottie.exporters.tgs import export_tgs

# Create a simple animation with a circle
animation = objects.Animation()
layer = objects.ShapeLayer()
animation.add_layer(layer)

# Add a circle shape
shape = objects.ShapeElement()
shape.shape = objects.Ellipse()
shape.shape.position = objects.Point(0.5, 0.5)
shape.shape.size = objects.Point(0.4, 0.4)
layer.add_shape(shape)

# Add a solid fill
fill = objects.Fill()
fill.color = objects.Color(1, 0, 0)  # Red
layer.add_shape(fill)

# Export to TGS (Telegram Sticker)
with open('sticker.tgs', 'wb') as f:
    export_tgs(animation, f)
print('Done')