Directory `macros/latex/contrib/animategif`

README.md

animategif — animated GIFs in PDF documents

$A beamer slide in which \animategif plays a matplotlib animation of gradient descent$ _{Every frame above is a page of a real beamer PDF, rendered by poppler
(source: [`docs/hero`](https://github.com/Ramlaoui/animategif/tree/main/docs/hero)).}

\usepackage{animategif}
...
\animategif[width=6cm]{movie}   % movie.gif

animategif embeds an animated GIF as a PDF animation, straight from the .gif file. It decodes the GIF itself, in pure Lua, so ImageMagick and other external programs are not needed, and it hands the frames to the animate package.

Follows the GIF: per-frame delays, disposal methods, transparency, interlacing, local palettes and loop count.
Small PDFs: frames become indexed PNGs, and only the pixels that change between frames are stored. Identical frames cost nothing.
Cached: each GIF is decoded once, into animategif-cache/.
Options: frames=10-40, step=2, speed=0.5, fps=12, plays=3, downsample=2, still=last, plus any animate option (controls, poster=last, …).
Beamer handouts get still images automatically.

Engines

Engine	Needs
LuaLaTeX	nothing (decodes in-process)
pdfLaTeX, XeLaTeX	`-shell-escape` (runs `texlua animategif.lua`)
any engine, cache already filled	nothing

Ship animategif-cache/ with your sources (e.g. to arXiv or a journal) and the document compiles anywhere without shell escape.

Viewers

Animations play in viewers that run animate's JavaScript: Adobe Acrobat/Reader, KDE Okular, PDF-XChange and Foxit Reader. Other viewers show a poster frame (the first frame by default, or set poster=last).

Installation

Once the package is on CTAN, TeX Live and MiKTeX will install it. Until then, put animategif.sty and animategif.lua next to your document, or install them into your TEXMF tree with l3build install.

Documentation

See animategif.pdf or build it with l3build doc. texlua animategif.lua info movie.gif prints a GIF's size, frame count, duration and loop count.

Development

test/verify.sh: decodes the test GIFs with several option sets, rebuilds every displayed frame from the stacked images exactly as the timeline shows it, and compares it pixel by pixel (and its delay) with ImageMagick.
l3build doc: builds the manual.
l3build ctan: builds the CTAN archive.

License

Download the contents of this package in one zip archive (159.9k).

Animategif – Embed animated GIF files in PDF documents, decoded in pure Lua

The package provides \animategif{file.gif}, which embeds an animated GIF as a PDF animation. The GIF is decoded in pure Lua – in-process with LuaLaTeX, or with texlua through shell escape with pdfLaTeX and XeLaTeX – so no external programs such as ImageMagick are needed. Frames are written as compact PNG images, storing only the pixels that change between frames, and cached. The animate package then embeds them with a timeline that follows the GIF's per-frame delays, disposal methods, transparency and loop count. Options select frame ranges, change the speed or number of plays, downsample, or include a single frame as a still image (automatically in beamer handouts).

Package	Animategif
Support	https://github.com/Ramlaoui/animategif/issues
Repository	https://github.com/Ramlaoui/animategif
Version	1.0.0 2026-10-06
Licenses	The LaTeX Project Public License 1.3c
Copyright	2026 Ali Ramlaoui
Maintainer	Ali Ramlaoui
Topics	Use LuaTeX Graphics motion Graphics include

Directory macros/latex/contrib/animategif