Package: lottie
Python LottieA Python framework to work with Lottie files and Telegram animated stickers.Quick startThis section describes some common things you might want to do without having
to read the whole READMEInstallationpip install lottieConverting into imagesThis package provide the scriptlottie_convert.py, it's precise location
depends on how you installed python-lottie.For PNG, GIF, and Webp you have to installcairosvgandpillow.To render a still image:lottie_convert.py input_file.json output_file.png --frame 30To render an animated image (GIF or WebP):lottie_convert.py input_file.json output_file.webpA list of supported formats is described in the section "Supported Formats" below.Turning GIF and such into animationsThe lottie format is for vector graphics, this means converting raster images
usually doesn't work too well.That said, python-lottie does support a few different algorithms to import
raster images, the process is a bit slow for larger images but use it with caution.To use the potrace vectorization library, install the extras tagged as "trace".Once set up, just invokelottie_convert.pyusing the vectorization algorithmlottie_convert.py input_file.gif output_file.json --bmp-mode traceFor pixel art, you can use thepizelalgorithm, which doesn't require potracelottie_convert.py input_file.gif output_file.json --bmp-mode pixelIf you are ok with keeping raster images as such, you can use the default modelottie_convert.py input_file.gif output_file.jsonConverting Telegram animated stickers (tgs)This format is natively supported by python lottie, but telegram doesn't
support all of the features supported by lottie
(see the section labeled "Supported After Effects Features" for details).When converting from tgs, nothing special is needed as it's handled as a lottie animation.lottie_convert.py AnimatedSticker.tgs output_file.webpBut when converting into animated stickers, you might end up with a file that
Telegram doesn't recognize. To help with this, by defaultlottie_convert.pywill scale the animation to be the right size and framerate.
It will also print out any warnings related to unsupported features.
Everything else works like any other conversion:lottie_convert.py input_file.json output_file.tgsIf you want to see the same warnings for an existing tgs file usetgs_check.pytgs_check.py AnimatedSticker.tgsCreating animations from scratchSee the examples athttps://mattbas.gitlab.io/python-lottie/examples.htmland read the available lottie objects athttps://mattbas.gitlab.io/python-lottie/group__Lottie.html#detailsFeaturesHere is a list of features of the lottie python framework:Loading compressed TGS and uncompressed lottie JSONManipulation of lottie objectsSimple 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 rotationsAnimation easing functionsInverse Kinematic solverPretty printing and comparison of lottie filesRendering text as shapesSupported FormatsFormatImportImport AnimatedExportExport Animatedlottie👍👍👍👍tgs👍👍👍👍SVG👍👍👍⛔️SVGz👍👍👍⛔️PNG👍👍[^frames]👍⛔️Synfig👍👍👍👍WebP👍👍👍👍dotLottie👍👍👍👍PostScript⛔️⛔️👍⛔️PDF⛔️⛔️👍⛔️BMP👍👍[^frames]⛔️⛔️GIF👍👍👍👍TIFF👍👍👍👍MP4⛔️⛔️👍👍AVI⛔️⛔️👍👍WebM⛔️⛔️👍👍HTML⛔️⛔️👍👍Blender👍[^blend]👍[^blend]⛔️⛔️Krita👍⛔️⛔️⛔️[^frames]: Importing multiple images as frames[^blend]: Conversion available as a Blender addonScriptspython-lottie provides several scripts to convert or manage lottie animations.
For full documentation seehttps://mattbas.gitlab.io/python-lottie/scripts.htmlThe main one islottie_convert.py, which can be used to convert between the supported formats.There is also the scriptlottie_gui.pywhich provides a graphical interface for lottie playback.InstallationDownloadsThe packages for the various applications listed below can be downloaded from here:ReleasesDevelopment SnapshotSynfigThere's a Synfig studio plugin to export telegram stickers.
To install, just copy (or symlink) ./addons/synfig/pylot-exporter
into the synfig plugin directory.
You might have to copy ./lib/lottie in there as well.InkscapeThere 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 extensionsNote that the extensions require Python 3.
If they are run with a python 2 interpreter, they will try to run themselves usingpython3.They also need the lottie framework to be in the python path, otherwise you can manually
set the path on the import/export dialogues.See alsohttps://inkscape.org/~mattia.basaglia/%E2%98%85tgslottie-importexportBlenderThere 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 bymake.PipYou can install from pypi:pip install lottiefrom git:pip install git+https://gitlab.com/mattbas/python-lottie.git@masterfor the source directory:pip install /path/to/the/sources # this is the path where setup.py is locatedRequirementsPython 3.Optional RequirementsIn order to provide lean installations, this framework doesn't have dependencies
for its core functionality.To add support for extra formats or advanced functionality, you can install
additional packages.These requirements are declared as extra in the Pypi package,
follows a table listing dependencies and featuresPackagesExtraFeaturepillowimagesTo load image assetsglaxnimatePNGTo export PNGcairosvgPDFTo export PNG / PDF / PSglaxnimate,pillowGIFTo export GIF and animated WebPfonttoolstextTo render text as shapesgraphemeemojiAdding emoji support to text renderingcairosvg,numpy, Python OpenCV 2videoTo export videoglaxnimatetraceTo convert raster images into vectorsQScintillaGUIGrafical user interface utilitiescoverageTo show unit test coverage, used optionally bytest.shIf intalling from pip, you can install optional requirements like so:pip install lottie[GIF]The above example will ensurecairosvgandpilloware installed.
For more details seehttps://pip.pypa.io/en/latest/reference/pip_install/#examples.For convenience, an additional extra requirements is defined,
so you can install all dependencies at once:pip install lottie[all]If you are using python-lottie from source you can runpip install -r requirements.txtWhich will install all the requirements (except for pypotrace, as that package has some issues)Telegram Animated StickersI 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://mattbas.gitlab.io/python-lottie/group__Lottie.html#lottie_jsonMaking your own exporters convertersLottie formatIf 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 = lottie.Animation()
# ...
json.dump(foo.to_dict(), output_file)I'm also creating a proper documentation for the format, see:https://mattbas.gitlab.io/tgs/group__Lottie.html#detailsTGS changesNothing major, just ensure the root JSON object hastgs: 1GzippingThe tgs file is the JSON described above compressed into a gzip,
and renamed to .tgsLicenseAGPLv3+https://www.gnu.org/licenses/agpl-3.0.en.htmlCreditsCopyright 2019 (C) Mattia BasagliaLinksDocumentationhttps://mattbas.gitlab.io/python-lottie/index.htmlCodehttps://gitlab.com/mattbas/python-lottie/Chathttps://t.me/tgs_stuffDownloadhttps://mattbas.gitlab.io/python-lottie/downloads.htmlHere 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.IssuesYou can report any issue in the tracker on gitlab:https://gitlab.com/mattbas/python-lottie/-/issuesSupported After Effects FeaturesCompare withhttp://airbnb.io/lottie/#/supported-featuresLegend👍 Supported❔ Unknown / untested⛔️ Not supportedpython-lottierefers to this framework in generalTelegramrefers to features supported by telegram animated stickersSVGrefers 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_stickerslists 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.Shapespython-lottieTelegramSVGShape👍👍👍Ellipse👍👍👍Rectangle👍👍👍Rounded Rectangle👍👍👍Polystar👍👍[^unsupported]👍Group👍👍👍Trim Path (individually)👍👍👍Trim Path (simultaneously)👍👍👍Fillspython-lottieTelegramSVGColor👍👍👍Opacity👍👍👍Radial Gradient👍👍👍Linear Gradient👍👍👍Fill Rule👍👍👍Strokespython-lottieTelegramSVGColor👍👍👍Opacity👍👍👍Width👍👍👍Line Cap👍👍👍Line Join👍👍👍Miter Limit👍👍👍Dashes👍👍👍Gradient👍👍[^unsupported]👍Transformspython-lottieTelegramSVGPosition👍👍👍Position (separated X/Y)👍👍👍Scale👍👍👍Rotation👍👍👍Anchor Point👍👍👍Opacity👍👍👍Parenting👍👍👍Skew👍⛔️[^bug]👍Auto Orient👍👍[^unsupported]👍Interpolationpython-lottieTelegramSVGLinear Interpolation👍👍👍Bezier Interpolation👍👍👍Hold Interpolation👍👍👍Spatial Bezier Interpolation👍👍👍Rove Across Time⛔️⛔️[^untested]⛔️Maskspython-lottieTelegramSVGMask Path👍👍[^unsupported]👍Mask Opacity👍👍[^unsupported]👍Add👍👍[^unsupported]⛔️Subtract👍👍[^unsupported]⛔️Intersect👍👍[^unsupported]👍Lighten👍👍[^unsupported]⛔️Darken👍👍[^unsupported]⛔️Difference👍👍[^unsupported]⛔️Expansion👍👍[^unsupported]⛔️Feather👍👍[^unsupported]⛔️Mattespython-lottieTelegramSVGAlpha Matte👍⛔️[^dok]👍Alpha Inverted Matte👍⛔️[^dok]⛔️Luma Matte👍⛔️[^dok]👍Luma Inverted Matte👍⛔️[^dok]⛔️Merge Pathspython-lottieTelegramSVGMerge⛔️⛔️[^untested]⛔️Add⛔️⛔️[^untested]⛔️Subtract⛔️⛔️[^untested]⛔️Intersect⛔️⛔️[^untested]⛔️Exclude Intersection⛔️⛔️[^untested]⛔️Layer Effectspython-lottieTelegramSVGFill👍⛔️⛔️Stroke👍⛔️⛔️Tint👍⛔️⛔️Tritone👍⛔️⛔️Levels Individual Controls👍⛔️⛔️Text[^text]python-lottieTelegramSVGGlyphs👍⛔️⛔️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⛔️⛔️⛔️Otherpython-lottieTelegramSVGExpressions⛔️⛔️[^untested]⛔️Images👍⛔️👍Precomps👍👍👍Time Stretch👍⛔️⛔️Time remap👍⛔️[^dok]👍Markers⛔️⛔️[^untested]⛔️3D Layers👍⛔️[^untested]⛔️Repeaters👍👍[^unsupported]👍Solids👍👍[^unsupported]👍[^text]: Note thatpython-lottieoffers an alternative to lottie text layers, and can render
text as shapes, so that is supported everywhere[^untested]: Marked as unsupported but I haven't tested it[^bug]: Not listed as unsupported, maybe a bug?[^dok]: Works on telegram desktop[^unsupported]: Marked as unsupported