Skip to main content

A framework to work with lottie / tgs files

Project description

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/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)

  • bin/tgscheck.py

    Checks a lottie or tgs file to see if it's compatible with telegram stickers

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. You might have to copy ./lib/tgs in there as well.

You can download a zipfile from http://mattia.basaglia.gitlab.io/tgs/downloads.html

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

You can download a zipfile from http://mattia.basaglia.gitlab.io/tgs/downloads.html

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.

You can download a zipfile from http://mattia.basaglia.gitlab.io/tgs/downloads.html

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
  • 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

Supported Formats

Format Import Import Animated Export Export Animated
lottie ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
tgs ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
SVG ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ โ›”๏ธ
SVGz ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ โ›”๏ธ
PNG ๐Ÿ‘ ๐Ÿ‘[^frames] ๐Ÿ‘ โ›”๏ธ
Synfig ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
WebP ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
dotLottie ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
PostScript โ›”๏ธ โ›”๏ธ ๐Ÿ‘ โ›”๏ธ
PDF โ›”๏ธ โ›”๏ธ ๐Ÿ‘ โ›”๏ธ
BMP ๐Ÿ‘ ๐Ÿ‘[^frames] โ›”๏ธ โ›”๏ธ
GIF ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
TIFF ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
MP4 โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
AVI โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
WebM โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
HTML โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
Blender ๐Ÿ‘[^blend] ๐Ÿ‘[^blend] โ›”๏ธ โ›”๏ธ

[^frames]: Importing multiple images as frames

[^blend]: Conversion available as a Blender addon

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

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.

Supported After Effects Features

Compare with http://airbnb.io/lottie/#/supported-features

Legend

  • ๐Ÿ‘ Supported
  • โ” Unknown / untested
  • โ›”๏ธ Not supported
  • tgs refers to this framework in general
  • Telegram refers to features supported by telegram animated stickers
  • SVG refers to the exported SVG images from this framework, features supported here will also reflect on other formats (such as video, png, and similar)

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.

Shapes tgs Telegram SVG
Shape ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Ellipse ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rectangle ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rounded Rectangle ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Polystar ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘
Group ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Trim Path (individually) ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Trim Path (simultaneously) ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Fills tgs Telegram SVG
Color ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Opacity ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Radial Gradient ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Linear Gradient ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Fill Rule ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Strokes tgs Telegram SVG
Color ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Opacity ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Width ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Line Cap ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Line Join ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Miter Limit ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Dashes ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Gradient ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘
Transforms tgs Telegram SVG
Position ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Position (separated X/Y) ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Scale ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rotation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Anchor Point ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Opacity ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Parenting ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Skew ๐Ÿ‘ โ›”๏ธ[^bug] ๐Ÿ‘
Auto Orient ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘
Interpolation tgs Telegram SVG
Linear Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Bezier Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Hold Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Spatial Bezier Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rove Across Time โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Masks tgs Telegram SVG
Mask Path ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘
Mask Opacity ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘
Add ๐Ÿ‘ ๐Ÿ‘[^unsuported] โ›”๏ธ
Subtract ๐Ÿ‘ ๐Ÿ‘[^unsuported] โ›”๏ธ
Intersect ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘
Lighten ๐Ÿ‘ ๐Ÿ‘[^unsuported] โ›”๏ธ
Darken ๐Ÿ‘ ๐Ÿ‘[^unsuported] โ›”๏ธ
Difference ๐Ÿ‘ ๐Ÿ‘[^unsuported] โ›”๏ธ
Expansion ๐Ÿ‘ ๐Ÿ‘[^unsuported] โ›”๏ธ
Feather ๐Ÿ‘ ๐Ÿ‘[^unsuported] โ›”๏ธ
Mattes tgs Telegram SVG
Alpha Matte ๐Ÿ‘ โ›”๏ธ[^dok] โ›”๏ธ
Alpha Inverted Matte ๐Ÿ‘ โ›”๏ธ[^dok] โ›”๏ธ
Luma Matte ๐Ÿ‘ โ›”๏ธ[^dok] โ›”๏ธ
Luma Inverted Matte ๐Ÿ‘ โ›”๏ธ[^dok] โ›”๏ธ
Merge Paths tgs Telegram SVG
Merge โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Add โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Subtract โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Intersect โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Exclude Intersection โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Layer Effects tgs Telegram SVG
Fill ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Stroke ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Tint ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Tritone ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Levels Individual Controls ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Text [^text] tgs Telegram SVG
Glyphs ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Fonts ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Transform ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Fill ๐Ÿ‘ โ›”๏ธ ๐Ÿ‘
Stroke ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Tracking โ›”๏ธ โ›”๏ธ โ›”๏ธ
Anchor point grouping โ›”๏ธ โ›”๏ธ โ›”๏ธ
Text Path โ›”๏ธ โ›”๏ธ โ›”๏ธ
Per-character 3D โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Units) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Based on) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Amount) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Shape) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Ease High) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Ease Low) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Randomize order) โ›”๏ธ โ›”๏ธ โ›”๏ธ
expression selector โ›”๏ธ โ›”๏ธ โ›”๏ธ
Other tgs Telegram SVG
Expressions โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Images ๐Ÿ‘ โ›”๏ธ ๐Ÿ‘
Precomps ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Time Stretch ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Time remap ๐Ÿ‘ โ›”๏ธ[^dok] ๐Ÿ‘
Markers โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
3D Layers ๐Ÿ‘ โ›”๏ธ[^untested] โ›”๏ธ
Repeaters ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘
Solids ๐Ÿ‘ ๐Ÿ‘[^unsuported] ๐Ÿ‘

[^text]: Note that tgs offers an alternative to lottie text layers, and can render text as shapes, so that is supported everywhere

[^untested]: Marked as unsuported but I haven't tested it

[^bug]: Not listed as unsupported, maybe a bug?

[^dok]: Works on telegram desktop

[^unsuported]: Marked as unsupported

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tgs-0.5.4.tar.gz (102.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page