A framework to work with lottie / tgs files
Telegram Animated Stickers Tools
A Python framework to work with Telegram animated stickers.
Script that can convert between several formats, including lottie / TGS
Prints the given tgs / lottie file into a human-readable format
Shows a side-by-side diff of the human-readable rendition of two tgs / lottie files
Extracts a frame as SVG from a lottie/tgs file, has a couple more options than
Converts a sequence of raster images into a lottie/tgs file, has a couple more options than
Shows the palette of a raster image, to use with
Converts a CSS color into a normalized array, as used in lottie
Pretty prints a JSON file (useful to debug / diff lottie files)
Pretty prints two JSON files side by side, highlighting differences (useful to debug / diff lottie files)
Pretty prints a tgs / lottie file with more readable annotations (useful to debug / diff lottie files)
Pretty prints two tgs / lottie files side by side, highlighting differences (useful to debug / diff lottie files)
There's a Synfig studio plugin to export telegram stickers. To install, just copy (or symlink) ./addons/synfig/tgs-exporter into the synfig plugin directory.
(Note: the bulk of this code has nothing to do with this package)
There are some import/export extensions for inkscape.
Just copy (or symlink) the files under ./addons/inkscape to the inkscape extension directory. On my system that's ~/.config/inkscape/extensions/ but you can double check from Inkscape: Edit > Preferences... > System > User extensions
Note that the extensions require Python 3.
If they are run with a python 2 interpreter, they will try to run themselves using
They also need the tgs framework to be in the python path, otherwise you can manually set the path on the import/export dialogues.
There are some export addons for blender.
Copy (or symlink) the files under ./addons/blender to the Blender extension directory.
On my system that's ~/.config/blender/2.80/scripts/addons/ you can check available paths through the Blender Python console:
import addon_utils; print(addon_utils.paths())
You can also install the addon from Blender using the zipfile created by
You can install from pypi:
pip install tgs
pip install git+https://gitlab.com/mattia.basaglia/tgs.git@master
for the source directory
pip install /path/to/the/sources # this is the path where setup.py is located
coverageTo show unit test coverage, used optionally by
scipyTo convert raster images into vectors
pillowTo load image assets
cairosvgTo export PNG / PDF / PS
pillowTo export GIF
numpy, Python OpenCV 2 To export video
fonttoolsTo render text as shapes
Here is a list of features of the tgs python framework:
- Loading compressed TGS and uncompressed lottie JSON
- Importing SVG images
- Importing raster images and convert them into vectors
- Export lottie JSON or TGS
- Export (non-animated) SVG
- Export Synfig files
- Export PNG/PDF/PostScript
- Export GIF
- Export Video (MP4, AVI, WebM)
- Manipulation of lottie objects
- Simple animation presets (eg: shake, linear bounce)
- Bezier path animations (eg: follow path, making paths appear and disappear)
- Wave distortion animation (eg: for flags)
- Pseudo-3D rotations
- Animation easing functions
- Inverse Kinematic solver
- Pretty printing and comparison of lottie files
- Rendering text as shapes
I had to reverse engineer the format because Telegram couldn't be bothered providing the specs.
A TGS file is a gzip compressed JSON, the JSON data is described here: https://mattia.basaglia.gitlab.io/tgs/group__Lottie.html#lottie_json
Making your own exporters converters
If you can get the source image into lottie format, that's 90% of the work done.
I've created Python classes based the format schema and after effects documentation, which output the correct json. Eg:
foo = tgs.Animation() # ... json.dump(foo.to_dict(), output_file)
I'm also creating a proper documentation for the format, see: https://mattia.basaglia.gitlab.io/tgs/group__Lottie.html#details
Nothing major, just ensure the root JSON object has
The tgs file is the JSON described above compressed into a gzip, and renamed to .tgs
Telegram doesn't support everything in the Lottie format. https://core.telegram.org/animated_stickers lists some things that are unsupported but what is listed there isn't correct.
There are several things marked as unsupported in telegram animated stickers that are actually supported:
- Mattes (Works on desktop but not on Android)
- Star Shapes
- Gradient Strokes
The following things are actually unsupported:
- Layer Effects
- Skew transforms (this isn't listed in the unsupported features)
- Animated layer transforms (not listed as unsupported)
Things marked as unsupported that I haven't tested:
- 3D Layers
- Merge Paths
- Time Stretching
- Time Remapping
- Auto-Oriented Layers
Copyright 2019 (C) Mattia Basaglia
Here you can download packages for pip, blender, and inkscape before they are released. These packages always have the latest features but they might be unstable.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size tgs-0.3.5.tar.gz (72.9 kB)||File type Source||Python version None||Upload date||Hashes View hashes|