tgs 0.3.5

A framework to work with lottie / tgs files

Telegram Animated Stickers Tools

A Python framework to work with Telegram animated stickers.

Scripts

• bin/tgsconvert.py

  Script that can convert between several formats, including lottie / TGS

• bin/tgscat.py

  Prints the given tgs / lottie file into a human-readable format

• bin/tgsdiff.py

  Shows a side-by-side diff of the human-readable rendition of two tgs / lottie files

• bin/tgs2svg.py

  Extracts a frame as SVG from a lottie/tgs file, has a couple more options than bin/tgsconvert.py

• bin/raster2tgs.py

  Converts a sequence of raster images into a lottie/tgs file, has a couple more options than bin/tgsconvert.py

• bin/raster_palette.py

  Shows the palette of a raster image, to use with bin/raster2tgs.py

• bin/tgscolor.py

  Converts a CSS color into a normalized array, as used in lottie

• bin/jsoncat.py

  Pretty prints a JSON file (useful to debug / diff lottie files)

• bin/jsondiff.py

  Pretty prints two JSON files side by side, highlighting differences (useful to debug / diff lottie files)

• bin/tgscat.py

  Pretty prints a tgs / lottie file with more readable annotations (useful to debug / diff lottie files)

• bin/tgsdiff.py

  Pretty prints two tgs / lottie files side by side, highlighting differences (useful to debug / diff lottie files)

Installation

Synfig

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)

Inkscape

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

They also need the tgs framework to be in the python path, otherwise you can manually set the path on the import/export dialogues.

See also https://inkscape.org/~mattia.basaglia/%E2%98%85tgslottie-importexport

Blender

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

Pip

You can install from pypi:

pip install tgs

from git:

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

Requirements

Python 3.

Optional Requirements

• coverage To show unit test coverage, used optionally by test.sh
• pillow, pypotrace>=0.2, numpy, scipy To convert raster images into vectors
• pillow To load image assets
• cairosvg To export PNG / PDF / PS
• cairosvg, pillow To export GIF
• cairosvg, numpy, Python OpenCV 2 To export video
• fonttools To render text as shapes

Features

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

Reverse Engineering

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

Lottie format

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

TGS changes

Nothing major, just ensure the root JSON object has tgs: 1

Gzipping

The tgs file is the JSON described above compressed into a gzip, and renamed to .tgs

Unsupported features

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:

• Masks
• Mattes (Works on desktop but not on Android)
• Star Shapes
• Gradient Strokes
• Repeaters
• Solids

The following things are actually unsupported:

• Layer Effects
• Images
• Skew transforms (this isn't listed in the unsupported features)
• Texts
• Animated layer transforms (not listed as unsupported)

Things marked as unsupported that I haven't tested:

• Expressions
• 3D Layers
• Merge Paths
• Time Stretching
• Time Remapping
• Auto-Oriented Layers

License

AGPLv3+ https://www.gnu.org/licenses/agpl-3.0.en.html

Credits

Copyright 2019 (C) Mattia Basaglia

Links

Documentation

http://mattia.basaglia.gitlab.io/tgs/index.html

Code

https://gitlab.com/mattia.basaglia/tgs/

Chat

https://t.me/tgs_stuff

Download

https://gitlab.com/mattia.basaglia/tgs/-/jobs/artifacts/master/download?job=build

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.