summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/animate/animate.tex
blob: 1cabe9c9fef1418046bb811070d786ff2f22fb53 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
\listfiles
% Copyright 2007--\today Alexander Grahn
%
% This material is subject to the LaTeX Project Public License. See
%    http://mirrors.ctan.org/macros/latex/base/lppl.txt
% for the details of that license.
%
\ifdefined\outputmode\outputmode=0\fi
\ifdefined\pdfoutput\pdfoutput=0\fi
\documentclass[a4paper]{article}
\frenchspacing
\usepackage[buttonbg=0.9]{animate}
\usepackage[UKenglish]{babel}
\usepackage{pst-3dplot}
\usepackage{pst-node,pst-plot,pst-tools,pst-text,pst-ode}
\usepackage{media9}
\usepackage{intcalc}
\usepackage{graphicx}
\graphicspath{{files/}}
\addmediapath{files}
\usepackage{color}
\usepackage{textcomp}
\usepackage{mflogo}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
%\usepackage{lmodern}
  \usepackage[tt=false]{libertine} %override beramono (doesn't look like tt font)
  \usepackage{libertinust1math}
\usepackage[protrusion]{microtype}
%\usepackage{ifpdf}
\usepackage{parskip}
\usepackage{tabls}
\usepackage{multirow}
\usepackage[bookmarksnumbered,linktocpage]{hyperref}
\usepackage[ocgcolorlinks]{ocgx2}
\usepackage{breakurl}
\usepackage{amsmath}
\usepackage{fancyvrb}
\usepackage{tabularx}
\usepackage[all]{hypcap}
\usepackage{listings}
\lstset{basicstyle=\ttfamily,columns=fullflexible,language={[LaTeX]TeX},commentstyle=\color{gray}}

\clubpenalty=10000
\widowpenalty=10000
\displaywidowpenalty=10000
\renewcommand{\textfraction}{0.0}
\renewcommand{\topfraction}{1.0}
\renewcommand{\bottomfraction}{1.0}

\makeatletter
\renewcommand{\fnum@figure}[1]{\figurename~\thefigure}
\newcommand\myparagraph{\@startsection{paragraph}{3}{\z@}%
                                     {\parskip}%
                                     {0.001\parskip}%
                                     {\itshape\normalsize}}
\makeatother

%\ifpdf
%  \makeatletter
%  \@latex@error{This document contains PSTricks code.\MessageBreak Please compile it using the following commands:\MessageBreak\MessageBreak latex, dvips, ps2pdf\MessageBreak\MessageBreak Don't use option `-Ppdf` with dvips}
%  \makeatother
%\fi

\def\keywords{include portable PDF animation SVG animation animated PDF animated SVG dvisvgm html TeX4ht web animating embed animated graphics LaTeX pdfLaTeX LuaLaTeX PSTricks pgf TikZ LaTeX-picture MetaPost inline graphics vector graphics animated GIF LaTeX dvips ps2pdf dvipdfmx XeLaTeX JavaScript Acrobat Reader KDE Okular PDF-XChange Foxit Reader Firefox Chrome Chromium}
\hypersetup{
  pdftitle={The animate Package},
  pdfsubject={Documentation},
  pdfauthor={Alexander Grahn},
  pdfkeywords={\keywords},
  allcolors=blue
}

\def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX}
\def\XeTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\TeX}
\def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX}

\def\parsedate#1/#2/#3\relax{
  \def\year{#1}
  \def\month{#2}
  \def\day{#3}
}

\hyphenation{Ja-va-Script pro-vid-ed}
\makeatletter
\let\animVersion\@anim@version
\makeatother

\begin{document}
\title{The {\sffamily animate} Package}
\begingroup
\makeatletter
\def\@anim@sanitizeColon{}\def\@anim@sanitizeJS{}\def\@anim@endsanitize{}
\expandafter\parsedate\animVersion\relax %set current date to package date
\makeatother
\author{Alexander Grahn \animategraphics[autoplay,loop,height=1.8ex,nomouse]{8}{bye_}{0}{3}\protect\footnote{Animated GIF taken from \href{http://www.phpBB.com}{phpBB} forum software and burst into a set of EPS files using \href{http://www.imagemagick.org}{ImageMagick} before embedding.}%
%\space\protect\footnote{Animations may run slowly if viewed in the Acrobat Reader browser plugin.}%
\\[1ex]\url{https://gitlab.com/agrahn/animate}}
\maketitle
\endgroup
\begin{abstract}
\raggedright

\noindent A LaTeX package for creating portable, JavaScript driven PDF and SVG animations from sets of vector graphics or raster image files or from inline graphics.
\vskip 0.2\baselineskip

\emph{Keywords}: \keywords
\end{abstract}
%\vspace{1.5cm}
\tableofcontents

%\newpage
\section{Introduction}
This package provides an interface for creating PDF and SVG files with animated content from sets of graphics or image files, from inline graphics, such as \LaTeX-picture, PSTricks or pgf/TikZ generated pictures, or just from typeset text. Unlike standard movie/video formats, package `animate' allows for animating vector graphics. The result is roughly similar to the SWF (Flash) format, although not as space-efficient.

Package `animate' supports the usual workflows for making PDF, i.\,e. pdf\LaTeX{}, Lua\-\LaTeX{}, \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller and \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+. For animated SVG, it supports the \verb+dvisvgm+ driver. The DVI/XDV used as input for \verb+dvisvgm+ can be generated with \LaTeX{}, Lua\LaTeX{} (in DVI mode with command `\verb+dvilualatex+') and \XeLaTeX{} (with option `\verb+--no-pdf+').

PDF files with animations can be viewed in Acrobat Reader (except on mobile devices), KDE Okular, PDF-XChange and Foxit Reader.

Animated SVG produced by means of \LaTeX{} and \verb+dvisvgm+ are self-sufficient files that can be embedded into HTML using the \verb+<object>+ tag or opened directly in a Web browser, such as Chromium or Firefox. Also, presentations, such as `beamer'-class documents, with embedded animations can be exported to SVG instead of PDF and viewed in a Web browser. SVG-capable Web browsers are standard on many platforms and operating systems and thus make SVG a very portable file format. A \LaTeX{} package for embedding video and audio into SVG is also available\cite{media4svg}.

The user interacts with the animation through optional animation controls or using the mouse like so: pressing the mouse button over the animation widget immediately pauses a playing animation and releasing it resumes playback. Pressing the shift-key at the same time reverses the playback direction. Keeping the mouse button pressed while moving the mouse pointer off the animation widget permanently pauses playback. On mobile devices, tapping on the animation toggles between play and pause.

%On mobile devices, interaction with an animated SVG is similar to that on desktop devices, just using finger touches instead of mouse button press/release. To permanently pause an animation without the pause button, touch the animation with a second finger, then lift both fingers off.


\section{Requirements}
\begin{trivlist}
%\item $\varepsilon$-\TeX
\item pdf\TeX{}, version $\ge1.40$, or Lua\TeX{}, version $\ge0.95$, for direct PDF output
\item Ghostscript, version $\ge9.15$, or Adobe Distiller for PS to PDF conversion
\item \verb+dvipdfmx+ for DVI to PDF conversion
\item dvipdfmx, version $\ge 20190503$, for DVI to PDF conversion
\item \verb+dvisvgm+ for DVI to SVG conversion (also requires Ghostscript)
\item PDF: Acrobat Reader, KDE Okular, PDF-XChange, Foxit Reader
\item SVG: Chromium-based browsers for best performance
\end{trivlist}

\section{Installation}
Unzip the file \href{http://mirrors.ctan.org/install/macros/latex/contrib/animate.tds.zip}{`animate.tds.zip'} into the local TDS root directory which can be found by running `\verb+kpsewhich -var-value TEXMFLOCAL+' on the command line.

After installation, update the filename database by running `\verb+texhash+' on the command line.

\TeX-Live and MiK\TeX{} users should run the package manager of their system for installation.

\section{Using the package}
First of all, read Section~\ref{sect:bugs} on problems related to this package. Then, invoke the package by putting the line
\begin{verbatim}
\usepackage[<package options>]{animate}
\end{verbatim}
to the preamble of the document source, i.\,e. somewhere between \verb+\documentclass+ and \verb+\begin{document}+.

`animate' honours the package options:
\begin{verbatim}
dvipdfmx
xetex
dvisvgm
export
autoplay
autopause
autoresume
loop
palindrome
draft
final
controls[=(all|true|on) |
          (none|false|off) | {[play][,step][,stop][,speed]}]
controlsaligned=left[+<indent>] | center | right[+<indent>]
width=<h-size>
height=<v-size> | totalheight=<v-size>
keepaspectratio
scale=<factor>
bb=<llx> <lly> <urx> <ury>
viewport=<llx> <lly> <urx> <ury>
trim=<left> <bottom> <right> <top>
clip
hiresbb
interpolate
pagebox=...
buttonsize=<size>
buttonbg=<colour>
buttonfg=<colour>
buttonalpha=<opacity>
step
nomouse
type=<file ext>
method=icon | widget | ocg
poster[=first | <num> | last | none]
alttext=none | {<alternative description>}
\end{verbatim}
Except for `\verb+dvipdfmx+', `\verb+xetex+', `\verb+dvisvgm+' and `\verb+export+', the listed package options are also available (among others) as command options and will be explained shortly. However, if used as package options they have global scope, taking effect on all animations in the document. In turn, command options locally override global settings. Options without an argument are boolean options and can be negated, with the exception of package-only options `\verb+dvipdfmx+', `\verb+xetex+', `\verb+dvisvgm+ and `\verb+export+', by appending `\verb+=false+'.

\begin{animateinline}[autoplay,loop,nomouse]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} Option `\verb+-Ppdf+' should \emph{not} be used with \verb+dvips+ when converting DVI to PostScript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call.

All workflows require the `graphicx' package to be loaded explicitly.

Options `\verb+dvipdfmx+' or `\verb+dvisvgm+' must be set for the document class, as in
%\verb+\documentclass[dvipdfmx,...]{...}+,
\begin{verbatim}
  \documentclass[dvipdfmx,...]{...}
\end{verbatim}
or
\begin{verbatim}
  \documentclass[dvisvgm,...]{...}
\end{verbatim}
because these drivers cannot be auto-detected by `animate', `graphicx' and other packages.

Usually, a second \LaTeX{} run is necessary to resolve internally created object references. A warning message will be issued if appropriate.

With option `\verb+export+', animation frames are output as individual pages of a multipage document that can be converted to other file formats, such as animated GIF. The `standalone' document class must be used together with `\verb+export+':
\begin{verbatim}
  \documentclass{standalone}
  \usepackage[export]{animate}
\end{verbatim}
or
\begin{verbatim}
  \documentclass[export]{standalone}
  \usepackage{animate}
\end{verbatim}

%\clearpage
\section{The user interface}
Package `animate' provides the command
\begin{verbatim}
\animategraphics[<options>]{<frame rate>}{<file basename>}{<first>}{<last>}
\end{verbatim}
and the environment
\begin{verbatim}
\begin{animateinline}[<options>]{<frame rate>}
    ... typeset material ...
\newframe[<frame rate>]
    ... typeset material ...
\newframe*[<frame rate>]
    ... typeset material ...
\newframe
\multiframe{<number of frames>}{[<variables>]}{
  ... repeated (parameterized) material ...
  \multiframebreak % optional!
}
\newframe*[...]    % some \newframe variant required
\multiframe{...}{...}{    % between two \multiframes
  ...
}
\end{animateinline}
\end{verbatim}

While \verb+\animategraphics+ can be used to assemble animations from sets of existing graphics files or from multipage PDF, the environment `\verb+animateinline+' is meant to create the animation from the typeset material it encloses. This material can be pictures drawn within the \LaTeX{} `\verb+picture+' environment or using the advanced capabilities of PSTricks or pgf/TikZ. Even ordinary textual material may be animated in this way. The parameter \verb+<frame rate>+ specifies the number of frames per second of the animation.

The \verb+\newframe+ command terminates a frame and starts the next one. It can be used only inside the `\verb+animateinline+' environment. There is a starred variant, \verb+\newframe*+. If placed after a particular frame, it causes the animation to pause at that frame. The animation continues as normal after clicking it again. Both \verb+\newframe+ variants take an optional argument that allows the frame rate to be changed in the middle of an animation.

The \verb+\multiframe+ command allows the construction of loops around pictures. The first argument \verb+<number of frames>+ does what one would expect it to do, the second argument \verb+<variables>+ is a comma-separated list of variable declarations. The list may be of arbitrary, even zero, length. Variables may be used to parameterize pictures which are defined in the loop body (third argument of \verb+\multiframe+). A single variable declaration has the form
\begin{verbatim}
  <variable name>=<initial value>+<increment>
\end{verbatim}
\verb+<variable name>+ is a sequence of one or more letters \emph{without} a leading backslash\footnote{This is different from {\tt\string\multido} (package `multido') where variable names have a leading `{\tt\textbackslash}' in the declaration.}. The first (and possibly only) letter of the variable name determines the type of the variable. There are three different types: integers (`\verb+i+', `\verb+I+'), reals (`\verb+n+', `\verb+N+', `\verb+r+', `\verb+R+') and dimensions or \LaTeX{} lengths (`\verb+d+', `\verb+D+'). Upon first execution of the loop body, the variable takes the value \verb+<initial value>+. Each further iteration increments the variable by \verb+<increment>+. Negative increments must be preceded by `\verb+-+'. Here are some examples: `\verb:i=1+2:', `\verb:Rx=10.0+-2.25:', `\verb:dim=20pt+1ex:'. Within the loop body, variables are expanded to their current value by prepending a backslash to the variable name, that is \verb+\i+, \verb+\Rx+ and \verb+\dim+ according to the previous examples. \verb+\multiframe+ must be surrounded by \verb+\begin{animateinline}+ and \verb+\end{animateinline}+ or by any of the \verb+\newframe+ variants. Two consecutive \verb+\multiframe+ commands must be separated by one of the \verb+\newframe+ variants.

\verb+\multiframebreak+ can be called to terminate a \verb+\multiframe+ loop prematurely, usually as part of a conditional statement. This command should preferably be placed near the end of the loop body in order not to produce an empty animation frame.

By default, the animation is built frame by frame in the order of inclusion of the embedded material. However, extended control of the order of appearance, superposition and repetition of the material is available through the `\verb+timeline+' option (see Section~\ref{sect:timeline}).

\myparagraph*{Sets of graphics files}
All files of the sequence should exist and be consecutively numbered. (Exception to this rule is allowed in connection with the `\verb+every+' option, see below.) {\tt <file base\-name>} is the leftmost part of the file name that is common to all members of the sequence. \verb+<first>+ is the number of the first and \verb+<last>+ the number of the last file in the set. If \verb+<first>+ is greater than \verb+<last>+, files are embedded in reverse order. File names may be simply numbered, such as $0\dots99$. If there are leading zeros, make sure that all file numbers have the same number of digits, such as $0000\dots0099$, and that the \verb+<first>+ and \verb+<last>+ arguments are filled in accordingly.

For example, given the sequence `frame\_5.png' through `frame\_50.png' from a possibly larger set that shall be used to build an animation running at 12 frames per second, the correct inclusion command would read
\begin{verbatim}
  \animategraphics{12}{frame_}{5}{50}
\end{verbatim}

The possible file formats depend on the output driver being used. In the case of \LaTeX{} + \verb+dvips+, files with the `eps' extension are at first searched for, followed by `mps' (\MP-generated PostScript) and `ps'. With pdf\LaTeX{} and Lua\LaTeX{} the searching order is: (1)~`pdf', (2)~`mps', (3)~`png', (4)~`jpg', (5)~`jpeg', (6)~`jp2'\footnotemark[1], (7)~`j2k'\footnotemark[1], (10)~`jpx'\footnotemark[1]\footnotetext[1]{Only Lua\LaTeX{} currently supports JPEG2000.}, with \XeLaTeX{} or \LaTeX{}+\verb+dvipdfmx+: (1)~`pdf', (2)~`mps', (3)~`eps', (4)~`ps', (5)~`png', (6)~`jpg', (7)~`jpeg', (8)~`bmp', and with \LaTeX{}+\verb+dvisvgm+: (1)~`pdf', (2)~`eps', (3)~`ps', (4)~`mps', (5)~`svg', (6)~`png', (7)~`jpg', (8)~`jpeg'. That is, files capable of storing vector graphics are found first. Make sure that all file names have \emph{lower case} extensions.

This searching procedure can be skipped thanks to the package and command option `\verb+type=<file ext>+'. It enforces the embedding of files with the given file name extension \verb+<file ext>+.

Command \verb+\graphicspath{}+ from the `graphicx' package can be used to specify directories to be browsed for graphics files.

\myparagraph*{Multipage PDF inclusion} %{\rm(pdf\LaTeX, \XeLaTeX, \texttt{dvipdfmx})} and JBIG2 {\rm(pdf\LaTeX)} inclusion}
Lua\LaTeX{}, pdf\LaTeX{}, \XeLaTeX{} and the \verb+dvipdfmx+ and \verb+dvisvgm+ backends are able to embed animation frames from multipage PDF. If the file `\verb+<file basename>+.pdf' exists, it is taken as a multipage document where each page represents one frame of the animation. In this case, the last two arguments, \verb+<first>+ \& \verb+<last>+, are interpreted differently from above; they specify a zero-based range of pages to be included in the animation. Either or both of them may be omitted, `\verb+{}+', in which case they default to $0$ and $n-1$, where $n$ is the total number of available pages. Arguments that fall outside this range are automatically corrected to the actual limits. If \verb+<first>+ is greater than \verb+<last>+, pages are embedded in reverse order. Again, option `\verb+type=<file ext>+' can be used to enforce a particular file extension.

For example, the line
\begin{verbatim}
  \animategraphics{12}{frames}{}{}
\end{verbatim}
would create an animation from all pages of the file `frames.pdf', running at 12 fps.

%\clearpage
\section{Command options}
The following options to \verb+\animategraphics+ and `\verb+animateinline+' have been provided.
\subsection{Basic options}
\begin{verbatim}
label=<label text>
\end{verbatim}
The animation is given a label, \verb+<label text>+, which must be unique. Labelling an animation enables its JavaScript programming interface by defining \verb+anim['<label+ \verb+text>']+, which is a JavaScript reference to the animation object. The animation object provides a number of properties and methods that can be used for controlling the animation playback from within user defined JavaScript. For details, see Section~\ref{sect:api}.
\begin{verbatim}
type=[<file ext>]
\end{verbatim}
Overrides the searching procedure for graphics files explained in the previous section and forces files with extension \verb+<file ext>+ to be used. Given with an empty argument as in `\verb+type=+', this option locally reinstates the default searching procedure if it was globally disabled through the package option.
\begin{verbatim}
poster[=first | <num> | last | none]
\end{verbatim}
Specifies which frame to display and print if the animation is not activated. The first frame is shown by default. Thus, `\verb+poster+' or `\verb+poster=first+' need not be explicitly set. A frame number \verb+<num>+ may as well be given; \verb+<num>+ is zero-based, that is, the first frame has number `0'.
\begin{verbatim}
every=<num>
\end{verbatim}
Build animation from every \verb+<num>+\emph{th} frame only. Skipped frames are discarded and not embedded into the document. In the case of \verb+\animategraphics+, skipped input files may be missing.
\begin{verbatim}
autopause
\end{verbatim}
Pause animation when the page is closed, instead of stopping and rewinding it to the default frame.
\begin{verbatim}
autoplay
\end{verbatim}
Start animation after the page has opened. Also resumes playback of a previously paused animation.
\begin{verbatim}
autoresume
\end{verbatim}
Resume previously paused animation when the page is opened again.
\begin{verbatim}
loop
\end{verbatim}
The animation restarts immediately after reaching the end.
\begin{verbatim}
palindrome
\end{verbatim}
The animation continuously plays forwards and backwards.
\begin{verbatim}
step
\end{verbatim}
Step through the animation one frame at a time per mouse-click. The \verb+<frame rate>+ argument will be ignored.
\begin{verbatim}
width=<h-size>
height=<v-size> | totalheight=<v-size>
keepaspectratio
\end{verbatim}
Resize the animation widget. If only one of `\verb+width+' or `\verb+[total]height+' is given, the other dimension of the animation widget is scaled to maintain the aspect ratio of the first frame's content. If both `\verb+width+' and `\verb+[total]height+' are given together with `\verb+keepaspectratio+', the first frame's content is resized to fit within \verb+<h-size>+ and \verb+<v-size>+ while maintaining its original aspect ratio. Any valid \TeX{} dimension is accepted as a parameter. In addition, the length commands \verb+\width+, \verb+\height+, \verb+\depth+ and \verb+\totalheight+ can be used to refer to the original dimensions of the first frame of the animated sequence.
\begin{verbatim}
scale=<factor>
\end{verbatim}
Scales the animation widget by \verb+<factor>+.
\begin{verbatim}
bb=<llx> <lly> <urx> <ury>
\end{verbatim}
(\verb+\animategraphics+ only.) The four, space separated arguments set the bounding box of the graphics files. Units can be omitted, in which case `bp' (PostScript points) is assumed.
\begin{verbatim}
viewport=<llx> <lly> <urx> <ury>
\end{verbatim}
(\verb+\animategraphics+ only.) This option takes four arguments, just like `\verb+bb+'. However, in this case the values are taken relative to the origin specified by the bounding box in the graphics files.
\begin{verbatim}
trim=<left> <bottom> <right> <top>
\end{verbatim}
(\verb+\animategraphics+ only.) Crops graphic at the edges. The four lengths specify the amount to be removed from or, if negative values have been provided, to be added to each side of the graphic.
\begin{verbatim}
clip
\end{verbatim}
(\verb+\animategraphics+ only.) Clips the graphic to the (possibly modified) bounding box.
\begin{verbatim}
pagebox=...
hiresbb
interpolate
\end{verbatim}
(\verb+\animategraphics+ only.) Options from the `graphics' bundle. Refer to the `graphics' package manual for their meaning.
\begin{verbatim}
controls[=all | true | on]
controls=(none | false | off) | {[play][,step][,stop][,speed]}
\end{verbatim}
Inserts control buttons below the animation widget. Visibility of buttons can be fine-tuned through optional keys. By default, if setting `\verb+controls+' alone, all available buttons are shown, while any of `\verb+none+', `\verb+false+' or `\verb+off+' suppresses them altogether. A comma-separated selection from `\verb+play+', `\verb+step+', `\verb+stop+' and `\verb+speed+' enables corresponding pairs or groups of buttons. Such a comma list must be enclosed in braces, i.\,e. \verb+controls={..., ..., ...}+. If all buttons are shown, their meaning is as follows, from left to right: stop \& first frame, step backwards, play backwards, play forwards, step forwards, stop \& last frame, decrease speed, default speed, increase speed. Both `play' buttons are replaced by a large `pause' button while the animation is playing.
\begin{verbatim}
controlsaligned=left[+<indent>] | center | right[+<indent>]
\end{verbatim}
Animation controls are centred below the animation widget by default. With this option one can choose between centred, flush-left or flush-right alignment. The optional \verb+<indent>+ inserts additional horizontal space that pushes the control buttons away from the left or right edge of the animation widget towards the opposite side. \verb+<indent>+ must be a valid \TeX{} dimension. Negative values may be used, as in
\begin{verbatim}
    controlsaligned=right+-4em,
\end{verbatim}
in which case control buttons protrude beyond the animation's right vertical edge by \verb+4em+.
\begin{verbatim}
buttonsize=<size>
\end{verbatim}
Changes the control button height to \verb+<size>+, which must be a valid \TeX{} dimension. The default button height is \verb+1.44em+ and thus scales with the current font size.
\begin{verbatim}
buttonbg=<colour>
buttonfg=<colour>
buttonalpha=<opacity>
\end{verbatim}
By default, control button widgets are drawn with black strokes on empty, fully transparent background. The background can be filled with colour using the first option, while the second option specifies the stroke colour. Option \verb+buttonalpha+ adds transparency to the background colour. The parameter \verb+<colour>+ is an array of colon-(\verb+:+)-separated numbers in the range from 0.0 to 1.0. The number of array elements determines the colour model in which the colour is defined: (1) gray value, (3) RGB, (4) CMYK. For example, `\verb+1+', `\verb+1:0.5:0.2+' and `\verb+0.5:0.3:0.7:0.1+' are valid colour specifications. The parameter \verb+<opacity>+ is a number between 0.0 and 1.0, where 0.0 produces fully transparent and 1.0 fully opaque buttons.
\begin{verbatim}
draft
final
\end{verbatim}
With `\verb+draft+' the animation is not embedded. Instead, a box with the exact dimensions of the animation is inserted. Option `\verb+final+' does the opposite as it forces the animation to be built and embedded. Both options can be used to reduce compilation time during authoring of a document. To get the most out of them it is recommended to set `\verb+draft+' globally as a package or class option and to set `\verb+final+' locally as a command option of the animation that is currently being worked on. After the document has been finished, the global `\verb+draft+' option can be removed to embed all animations.
\begin{verbatim}
nomouse
\end{verbatim}
Animation widget will not respond to mouse clicks. Unless the JavaScript interface, Sect.~\ref{sect:api}, p.~\pageref{sect:api}, is used to control the animation, it is recommended to also set at least one of the `\verb+autoplay+' or `\verb+controls+' options.
\begin{verbatim}
method=icon | widget | ocg
\end{verbatim}
The package implements three different animation methods. The `\verb+icon+' method is the default method and usually gives the best performance in terms of animation frame rate. `\verb+widget+' and `\verb+ocg+' are alternative animation methods. In rare cases (standalone animations without animation controls) method `\verb+ocg+' may lead to a better animation performance than the other two. Moreover, it allows overlaying animations with other typeset material, that is, playing animations in the page background.
\begin{verbatim}
measure
\end{verbatim}
Measures the frame rate during one cycle of the animation and prints the value to the JavaScript console of the Reader. (For testing purposes.)
\begin{verbatim}
alttext=none | {<alternative description>}
\end{verbatim}\hypertarget{beginend}{}%
Changes or suppresses alternative description text. The default is `{\ttfamily animation by animate\verb+[+\animVersion\verb+]+}'. This text is shown by some PDF viewers that are not capable of rendering JavaScript animations or used for accessibility purposes.
\begin{verbatim}
begin={<begin text>}
end={<end text>}
\end{verbatim}\hypertarget{beginend}{}%
(`\verb+animateinline+' only.) \verb+<begin text>+ and \verb+<end text>+ are inserted into the code at start and end of each frame. Mainly used for setting up some drawing environment, such as
\begin{verbatim}
  begin={\begin{pspicture}(... , ...)(... , ...)},
  end={\end{pspicture}}
\end{verbatim}
A short note on the `\verb+tikzpicture+' environment: Unlike `\verb+pspicture+', the `{\tt tikz\-pic\-ture}' environment is able to determine its size from the graphical objects it encloses. However, this may result in differently sized frames of a sequence, depending on the size and position of the graphical objects. Thus, in order to ensure that all frames of the sequence be displayed at the same scale in the animation widget, a common bounding box should be shared by the frames. A bounding box can be provided by means of an invisible `\verb+rectangle+' object:
\begin{verbatim}
  begin={
    \begin{tikzpicture}
    \useasboundingbox (... , ...) rectangle (... , ...);
  },
  end={\end{tikzpicture}}
\end{verbatim}

%\clearpage
\subsection{The `{\tt timeline}' option}\label{sect:timeline}
\begin{verbatim}
timeline=<timeline file>
\end{verbatim}
\verb+<timeline file>+ is a plain text file whose contents determines the order of appearance of the embedded material during the animation. It allows the user to freely rearrange, repeat and overlay the material at any point of the animation. This may greatly reduce the file size of the resulting PDF, as objects that do not change between several or all frames, such as coordinate axes or labels, can be embedded once and re-used in other frames of the animation. (Technically, this is done by the XObject referencing mechanism of PDF.)

If a timeline is associated with the animation, the graphics files or inline graphics embedded by \verb+\animategraphics+ and `\verb+animateinline+' no longer represent the actual frames of the animation. Rather, they are a collection of \emph{transparencies} that can be played with at will. However, it is now up to the author's responsibility to construct a timeline that makes use of \emph{each} of those transparencies and to put them into a sensible order. In order to identify the transparencies within the timeline file, they are numbered in the order of their inclusion, starting at zero.

A timeline-based animation can be thought of as a \emph{living stack} of translucent transparencies. Each animation frame is a snapshot of the stack viewed \emph{from above}. Transparencies are usually put on top of that stack and stay there for a given number of frames before expiring (becoming invisible). The lifetime of each transparency within the stack can be set individually. Once expired, a transparency can be put on the stack again, if desired. The stack may also be divided into an arbitrary number of \emph{sub-stacks} to facilitate the creation of layers, such as background, foreground and intermediate layers. Sub-stacks allow the insertion of transparencies at depth positions of the global stack other than just the top. It is important to keep the stack-like nature of animations in mind because graphical objects on transparencies at higher stack positions overlay the content of transparencies at lower stack positions.

\myparagraph*{General structure of the timeline file}
Each line of the timeline file that is not blank and which does not begin with a comment (`\verb+%+') corresponds to \emph{one} frame of the animation. There may be more transparencies than animation frames and vice-versa. A frame specification consists of three or four colon-(\verb+:+)-separated fields:
\begin{verbatim}
  [*]:[<frame rate>]:[<transparencies>][:<JavaScript>]
\end{verbatim}
While any field may be left blank, the first two colons are mandatory. The fourth field, \verb+<JavaScript>+, is explained on p.~\pageref{sect:jsfield}.

An asterisk (`\verb+*+') in the leftmost field causes the animation to pause at that frame, very much as a \verb+\newframe*+ would do; a number in the second field changes the frame rate of the animation section that follows. In connection with the `\verb+timeline+' option, the asterisk extension and the optional \verb+<frame rate>+ argument of \verb+\newframe+ cease to make sense and will be tacitly ignored if present.

The third field \verb+<transparencies>+ is a comma-separated \emph{list} of \emph{transparency specifications} that determines the transparencies to be put on the stack. Semicolons (\verb+;+) are used to separate sub-stacks (= layers) from each other. A \emph{single} transparency specification obeys the syntax
\begin{verbatim}
  <transparency ID>[x<number of frames>]
\end{verbatim}
where \verb+<transparency ID>+ is an integer number that identifies the transparency to be drawn into the current animation frame. As pointed out above, the transparencies are consecutively numbered in the order of their inclusion, starting at zero. The optional postfix `\verb+x<number of frames>+' specifies the number of consecutive frames within which the transparency is to appear. If omitted, a postfix of `\verb+x1+' is assumed, which causes the transparency to be shown in the current frame only. Obviously, \verb+<number of frames>+ must be a non-negative integer number. The meaning of postfix `\verb+x0+' is special; it causes the transparency to be shown in all frames, starting with the current one, until the end of the animation or until the animation sub-stack to which it belongs is explicitly cleared.

The letter `\verb+c+', if put into \verb+<transparencies>+, clears an animation sub-stack, that is, it causes all transparencies added so far to be removed from the sub-stack, overriding any \verb+<number of frames>+ value. The effect of `\verb+c+' is restricted to the sub-stack in which it appears. Thus, a `\verb+c+' must be applied to every sub-stack if the complete animation stack is to be cleared. Moreover, if applied, `\verb+c+' should go into the first position of the transparency list of a sub-stack because \emph{everything} in the sub-stack up to `\verb+c+' will be cleared.

%If a frame is composed of more than one transparency, transparency specifications on the left of the input line are closer to the background and will be overprinted by those on the right of the input line or which appear on subsequent lines of the timeline file. That is, the depth \emph{de}creases from left to right within \verb+<transparencies>+ as well as in top-down direction within the timeline file.
%Also, if there are transparency specifications which span several frames (using postfix `\verb+x<number of frames>+'), they will be overprinted by transparency specifications that appear on subsequent lines in the timeline file. That is, the depth decreases in top-down direction within the timeline file.

\myparagraph*{Timeline example with a single animation stack}
Table~\ref{tab:single} is an example of a single-stack animation. It lists the contents of a timeline file together with the resulting stack of transparencies. Note how the stack is strictly built from the bottom up as transparency specifications are read from left to right and line by line from the timeline file. In frame No. 4, the stack is first cleared before new transparencies are deposited on it. Also note that the stack is viewed from above and transparencies in higher stack position overprint the lower ones.

\begin{table}[h]\centering
\caption{Timeline example of a single-stack animation}\label{tab:single}
\begin{tabular}[t]{c|l|c}\hline
frame No. & timeline file & transparency stack\\\hline\hline
\multirow{2}{*}{0} & \multirow{2}{*}{\tt::0x0,1x2} & ---------1---------\\&&---------0---------\\\cline{1-1}\cline{3-3}
\multirow{3}{*}{1} & \multirow{3}{*}{\tt::2} & ---------2---------\\&&---------1---------\\&&---------0---------\\\cline{1-1}\cline{3-3}
\multirow{2}{*}{2} & \multirow{2}{*}{\tt::3} & ---------3---------\\&&---------0---------\\\cline{1-1}\cline{3-3}
\multirow{2}{*}{3} & \multirow{2}{*}{\tt::4} & ---------4---------\\&&---------0---------\\\cline{1-1}\cline{3-3}
\multirow{2}{*}{4} & \multirow{2}{*}{\tt::c,5x0,6} & ---------6---------\\&&---------5---------\\\cline{1-1}\cline{3-3}
\multirow{2}{*}{5} & \multirow{2}{*}{\tt::7} & ---------7---------\\&&---------5---------\\\cline{1-1}\cline{3-3}
\multirow{2}{*}{6} & \multirow{2}{*}{\tt::8} & ---------8---------\\&&---------5---------\\\cline{1-1}\cline{3-3}
\multirow{2}{*}{7} & \multirow{2}{*}{\tt::9} & ---------9---------\\&&---------5---------\\\hline
\end{tabular}
\end{table}

Figures~\ref{fig:taylor} and \ref{fig:lorenz} in Sect.~\ref{sect:examples} are animation examples with a single transparency stack.

\myparagraph*{Grouping objects into layers (= sub-stacks) using `{\tt;}'}
Due to the stack-like nature of the animation, the position of a transparency specification in the timeline file determines its \emph{depth} level in relation to other transparencies. The timeline file is processed line by line and from left to right. In a single-stack animation, the stack is strictly built from the bottom up, such that earlier transparencies are overprinted by more recent ones. This may turn out to be inconvenient in certain situations. For example, it might be desirable to change the background image in the middle of an animation without affecting objects that are located in the foreground. For this purpose, transparency specifications can be grouped into layers (sub-stacks) using the semicolon (\verb+;+) as a separator. New transparencies can now be put on top of the individual sub-stacks. After a line of the timeline file has been processed, the global stack is built by placing the sub-stacks on top of the other. Again, the left-to-right rule applies when determining the height of the sub-stacks in relation to each other within the global stack.

The layer concept is best illustrated by an example. In the timeline of Table~\ref{tab:multi}, transparencies are grouped into two sub-stacks only. One is reserved for the background images, transparencies No. 0 \& 1, to be exchanged in frame No. 3, as well as for two other transparencies, No. 7 \& 8, to be interspersed in frame No. 1. A second sub-stack takes the foreground objects that are successively added to the scene. The dotted lines in the third column of the table just mark the border between the two sub-stacks. In frame No. 3, `\verb+c+' first clears the bottom sub-stack before the new background image is inserted. (Instead, `\verb+x3+' could have been used with transparency No. 0 in frame No. 0.) As can be seen in the specifications of frames No. 2 \& 4, sub-stacks need not be explicitly populated; the leading semicolons just ensure the proper assignment of transparencies to animation sub-stacks.

\begin{table}[t]\centering
\caption{Timeline example with two sub-stacks}\label{tab:multi}
\begin{tabular}[t]{c|l|c}\hline
frame No. & timeline file & transparency stack\\\hline\hline
\multirow{3}{*}{0} & \multirow{3}{*}{\tt::\ \ 0x0 ; 2x0} & ---------2---------\\&&{\tiny\dotfill}\\&&---------0---------\\\cline{1-1}\cline{3-3}
\multirow{6}{*}{1} & \multirow{6}{*}{\tt::7,8x2 ; 3x0} & ---------3---------\\&&---------2---------\\&&\tiny\dotfill\\&&---------8---------\\&&---------7---------\\&&---------0---------\\\cline{1-1}\cline{3-3}
\multirow{6}{*}{2} & \multirow{6}{*}{\tt::\ \ \ \ \ \ ; 4x0} & ---------4---------\\&&---------3---------\\&&---------2---------\\&&\tiny\dotfill\\&&---------8---------\\&&---------0---------\\\cline{1-1}\cline{3-3}
\multirow{6}{*}{3} & \multirow{6}{*}{\tt::c,1x0 ; 5x0} & ---------5---------\\&&---------4---------\\&&---------3---------\\&&---------2---------\\&&\tiny\dotfill\\&&---------1---------\\\cline{1-1}\cline{3-3}
\multirow{7}{*}{4} & \multirow{7}{*}{\tt::\ \ \ \ \ \ ; 6x0} & ---------6---------\\&&---------5---------\\&&---------4---------\\&&---------3---------\\&&---------2---------\\&&\tiny\dotfill\\&&---------1---------\\\hline
\end{tabular}
\end{table}

%\small
%\begin{verbatim}
%  % <--layer 1--> <--layer 2-->
%  %
%  ::    0x49     ;   2x0,3x0    % transparency `0' used as background
%  ::             ;   4x0,5x0    % image during the first 49 frames
%  ::             ;   6x0,7x0
%  etc...
%  ::             ;  98x0,99x0
%  ::    1x0      ; 100x0,101x0  % transparency `1' used as new background
%  ::             ; 102x0,103x0  % image until end of animation
%  ::             ; 104x0,105x0
%  etc...
%\end{verbatim}
%\normalsize
%
%Note that \emph{without} setting up two layers, that is, by replacing the semicolons with commas, the foreground objects (transparencies 2 through 99) which have been added during the first 49 frames would be overprinted by the new background image, transparency 1, from frame 50 onward.

See the second animation, Fig.~\ref{fig:scarab}, in Sect.~\ref{sect:examples} for a working example that makes use of the timeline and the layer concept.

\myparagraph*{Associate JavaScript actions with animation frames}\label{sect:jsfield}
The optional fourth field \verb+<JavaScript>+ in a frame specification takes JavaScript code to be executed upon display of that frame. This could be used, for instance, to play a sound that was embedded using the `media9' \LaTeX{} package \cite{media9} or to execute JavaScript methods of the animation object. A non-trivial example is looping over a sub-range of frames which can be programmed by setting the `\verb+frameNum+' property of the animation object. See Section~\ref{sect:api} for details of the animation programming interface.

The backslash `\verb+\+' and percent `\verb+%+' characters retain their special meaning from \LaTeX{} and must be escaped by a backslash `\verb+\+' in the JavaScript code. The same applies to unbalanced braces `\verb+{+' and `\verb+}+'. Thus, a code line such as
\begin{verbatim}
  console.println('{}%}{\n');
\end{verbatim}
would have to look like
\begin{verbatim}
  console.println('{}\%\}\{\\n');
\end{verbatim}
in the timeline file. The first pair of braces are balancing themselves and do not need to be escaped.

Note that JavaScript is executed at the start of displaying the frame. If something is to be executed at the end of a particular frame, the \verb+<JavaScript>+ field should be added to the next frame in the timeline file. However, this is not possible for the last frame in a timeline file. Here, the `\verb+setTimeOut+' method can be used to delay the execution of commands:
\begin{verbatim}
  app.setTimeOut('anim.myanim.frameNum=5;', 0.5*anim.myanim.dt)
\end{verbatim}
In this example, the 6th frame will be displayed after half of the current frame's lifetime has elapsed.

\myparagraph*{Other things to note}
When designing the timeline, care should be taken not to include a transparency more than once into the \emph{same} animation frame. Besides the useless redundancy, this may slow down the animation speed in the Reader because the graphical objects of a multiply included transparency have to be rendered unnecessarily often at the same time. `animate' is smart enough to detect multiple inclusion and issues a warning message along with the transparency ID and the frame number if it occurs. Here is an example of a poorly designed timeline:
%\small
\begin{lstlisting}
  ::0
  ::1x0
  ::2
  ::3
  ::4,2
  ::5,1 % bad: transparency `1' included twice
  ::6
\end{lstlisting}
\normalsize
Also, `animate' finds and warns about transparencies that have never been used in an animation timeline. This may help to avoid dead code in the final PDF.

%\clearpage
\section{Programming interface}\label{sect:api}
The package provides a simple JavaScript programming interface which gives access to the animation objects in a PDF file. A particular animation property or method can be accessed by
\begin{verbatim}
  anim['<anim label>'].<property or method>
\end{verbatim}
or
\begin{verbatim}
  anim.<anim label>.<property or method>
\end{verbatim}
`\verb+anim+' is an array of animation object references. Animations must be labelled using the `\verb+label=...+' command option in order to be present in the `\verb+anim+' array. As usual, properties and methods are accessed via the dot notation. Properties and methods of the animation object are summarized in Tables \ref{tab:props} and \ref{tab:methods}.

\begin{table}[hbp]%[p]%[hbp]
\centering
\caption{Animation object properties}\label{tab:props}
\begin{tabularx}{\linewidth}[t]{lllX}\hline
name & type & access & description\\\hline\hline
{\tt numFrames} & Integer & read-only & Holds the total number of animation frames.\\
{\tt frameNum}  & Integer & read+write & Gets or sets the current frame being/to\,be displayed. Note that frame numbers are zero-based. Assigning a value less than zero or greater than {\tt numFrames-1} results in an error.\\
  {\tt fps} & Number & read+write & Gets or temporarily sets the animation frame rate (frames per second). Reset after reaching the end of a sequence, or if the frame rate is set in a timeline or by {\tt\string\newframe[<frame rate>]}. For scaling overall animation speed, consider using the \Verb+speed+ property. Assigning a value less than zero results in an error.\\
  {\tt speed} & Number & read+write & Globally scales animation speed. The value must be greater than zero. A value of {\tt 1} means `normal speed' as specified by the frame rate in the document source. Larger values mean `faster', values between zero and one mean `slower'.\\
{\tt dt} & Number & read-only & Holds the time span (milliseconds) for display of the current frame.\\
{\tt isPlaying} & Boolean & read-only & Holds the value {\tt true} if the animation is currently playing, {\tt false} otherwise.\\
{\tt playsFwd} & Boolean & read-only & Holds the value {\tt true} if the animation is played forward, independently of whether the animation is currently paused or not.\\
\hline
\end{tabularx}
\end{table}

\begin{table}[htp]%[p]%[htbp]
\centering
\caption{Animation object methods}\label{tab:methods}
\begin{tabularx}{\linewidth}[t]{lX}\hline
name & description\\\hline\hline
{\tt playFwd()} & Starts playing the animation in the forward direction, setting the properties {\tt isPlaying} and {\tt playsFwd} to {\tt true}.\\
{\tt playBwd()} & Starts playing the animation in the backward direction, setting {\tt isPlaying} to  {\tt true} and {\tt playsFwd} to {\tt false}.\\
{\tt pause()} & Pauses animation, setting {\tt isPlaying} to {\tt false}.\\
{\tt stopFirst()} & Stops animation and rewinds to the first frame. {\tt isPlaying} is set to false.\\
{\tt stopLast()} & Stops animation and goes to the last frame. {\tt isPlaying} is set to false.\\
\hline
\end{tabularx}
\end{table}

One potential use of the JavaScript interface could be within a timeline file associated with an animation. For example, loops over a sub-range of frames can be programmed by setting the `\verb+frameNum+' property. See Section~\ref{sect:timeline}, p.~\pageref{sect:jsfield} for details.

Also, the programming interface can be used to create custom buttons for playback control. The command \verb+\mediabutton+ from the `media9' package provides a convenient way for achieving this:
\begin{lstlisting}
  \usepackage{media9}
  \usepackage{animate}
  ...

  \animategraphics[label=my_anim]{12}{...}{...}{...}

  \mediabutton[
    jsaction={anim['my_anim'].playFwd();}
  ]{\fbox{Play}}
  \mediabutton[
    jsaction={anim['my_anim'].frameNum=5;}
  ]{\fbox{Goto 6th frame}}
\end{lstlisting}

\clearpage
\section{Examples}
\subsection{Animations from sets of files, using {\tt\textbackslash animategraphics}}\label{sect:examples}
Animations in this section are made from graphics files that were prepared with \MP. Run `\verb+mpost --tex=latex+' on the files ending in `.mp' in the `files' directory to generate the graphics files. Both examples make use of the `\verb+timeline+' option to reduce the resulting PDF file size.

The first example, Fig.~\ref{fig:taylor}, originally written by Jan Holeček~\cite{hol}, shows the exponential function $y=e^x$ and its approximation by Taylor polynomials of different degree. Below the animation, a custom button was inserted using the JavaScript programming interface and the \verb+\mediabutton+ command from the `media9' package.

%\small
\begin{lstlisting}
\documentclass{article}
\usepackage{animate}
\usepackage{media9}
\usepackage{graphicx}

\begin{filecontents}{timeline.txt}
::0x0 % coordinate system & y=e^x, repeated until last frame
::1   % one blue curve per frame
::2
::3
::4
::5
::6
::7
::8
\end{filecontents}

\begin{document}

\begin{center}
  \animategraphics[
    label=taylor,
    controls, loop,
    timeline=timeline.txt
  ]{4}{exp_}{0}{8}

  \mediabutton[
    jsaction={
      if(anim['taylor'].isPlaying)
        anim['taylor'].pause();
      else
        anim['taylor'].playFwd();
    }
  ]{\fbox{Play/Pause}}
\end{center}

\end{document}
\end{lstlisting}
%\normalsize
\begin{figure}\capstart
\centering
\begin{VerbatimOut}{timeline.txt}
::0x0 % coordinate system & y=e^x, repeated until last frame
::1   % one blue curve per frame
::2
::3
::4
::5
::6
::7
::8
\end{VerbatimOut}
\animategraphics[
  label=taylor,
  controls, loop,
  timeline=timeline.txt
]{4}{exp_}{0}{8}

\mediabutton[
  jsaction={
    if(anim['taylor'].isPlaying)
      anim['taylor'].pause();
    else
      anim['taylor'].playFwd();
  }
]{\fbox{Play/Pause}}
\caption{}\label{fig:taylor}
\end{figure}

The second, somewhat more complex example, Fig.~\ref{fig:scarab}, animates the geometric construction of a scarabaeus. In addition to the use of a timeline, it introduces the layer concept. This example is adapted from Maxime Chupin's original \MP{} source file \cite{chupin}. The present version separates stationary from moving parts of the drawing and saves them into different files. A total of 254 files, scarab\_0.mps through scarab\_253.mps, is written out by running `\verb+mpost --tex=latex+' on the source file `scarab.mp'. Files 0 through 100 contain the red line segments that make up the growing scarabaeus. Files 101 through 201 contain the moving construction lines and files 202 through 252 contain the gray lines which represent intermediate stages of the construction. The last file, No. 253, contains the coordinate axes, two stationary construction lines and the labels which do not move. A timeline file `scarab.tln' is written out on-the-fly during the \LaTeX{} run. It arranges the animation into three layers, forcing the gray lines into the background, the coordinate axes into the intermediate layer and the scarabaeus along with the moving construction lines into the foreground. The final animation consists of 101 individual frames.
\begin{figure}[t]
\centering
\newcounter{scarab}
\setcounter{scarab}{0}
\newcounter{blueline}
\setcounter{blueline}{101}
\newcounter{grayline}
\setcounter{grayline}{202}
%
\newwrite\TimeLineFile
\immediate\openout\TimeLineFile=scarab.tln
\whiledo{\thescarab<101}{
  \ifthenelse{\intcalcMod{\thescarab}{2}=0}{
    \immediate\write\TimeLineFile{::\thegrayline x0;253;\thescarab x0,\theblueline}
    \stepcounter{grayline}
  }{
    \immediate\write\TimeLineFile{::;253;\thescarab x0,\theblueline}
  }
  \stepcounter{scarab}
  \stepcounter{blueline}
}
\immediate\closeout\TimeLineFile
%
\animategraphics[
  type=mps,
  width=0.8\linewidth,
  controls,
  loop,
  timeline=scarab.tln
]{12}{scarab_}{0}{253}
%
\caption{}\label{fig:scarab}
\end{figure}

%\small
\begin{lstlisting}
\documentclass{article}
\usepackage{intcalc} %defines \intcalcMod for Modulo computation
\usepackage{animate}
\usepackage{graphicx}

\newcounter{scarab}
\setcounter{scarab}{0}
\newcounter{blueline}
\setcounter{blueline}{101}
\newcounter{grayline}
\setcounter{grayline}{202}

%write timeline file
\newwrite\TimeLineFile
\immediate\openout\TimeLineFile=scarab.tln
\whiledo{\thescarab<101}{
  \ifthenelse{\intcalcMod{\thescarab}{2}=0}{
    %a gray line is added to every 2nd frame
    \immediate\write\TimeLineFile{%
      ::\thegrayline x0;253;\thescarab x0,\theblueline}
    \stepcounter{grayline}
  }{
    \immediate\write\TimeLineFile{%
      ::;253;\thescarab x0,\theblueline}
  }
  \stepcounter{scarab}
  \stepcounter{blueline}
}
\immediate\closeout\TimeLineFile

\begin{document}

\begin{center}
  \animategraphics[
    width=0.8\linewidth,
    controls, loop,
    timeline=scarab.tln
  ]{12}{scarab_}{0}{253}
\end{center}

\end{document}
\end{lstlisting}
%\normalsize
\subsection{Animating PSTricks graphics, using `{\tt animateinline}' environment}
Fig.~\ref{fig:torus} is an inline graphics example adapted from \cite{gilg05}.
%\small
\begin{lstlisting}
\documentclass{article}
\usepackage{pst-3dplot}
\usepackage{animate}

%draws a torus sector
\newcommand{\torus}[2]{% #1: angle of the torus sector,
  %                      #2: linewidth of leading circle
  \psset{Beta=20,Alpha=50,linewidth=0.1pt,origin={0,0,0},unit=0.35}%
  \begin{pspicture}(-12.3,-6.3)(12.3,7)%
    \parametricplotThreeD[xPlotpoints=100](80,#1)(0,360){%
      t cos 2 mul 4 u sin 2 mul add mul
      t sin 2 mul 4 u sin 2 mul add mul
      u cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=75](0,360)(80,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=1,linewidth=#2](0,360)(#1,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
  \end{pspicture}%
}

\begin{document}

\begin{center}
\begin{animateinline}[poster=last, controls, palindrome]{12}%
  \multiframe{29}{iAngle=80+10, dLineWidth=2.9pt+-0.1pt}{%
    %iAngle = 80, 90, ..., 360 degrees
    %dLineWidth = 2.9pt, 2.8pt, ..., 0.1pt
    \torus{\iAngle}{\dLineWidth}%
  }%
\end{animateinline}%
\end{center}

\end{document}
\end{lstlisting}
%\normalsize

\begin{figure}
\centering
\newcommand{\torus}[2]{%
  \psset{Beta=20,Alpha=50,linewidth=0.1pt,origin={0,0,0},unit=0.35}%
  \begin{pspicture}(-12.3,-6.3)(12.3,7)%
    \parametricplotThreeD[xPlotpoints=100](80,#1)(0,360){%
      t cos 2 mul 4 u sin 2 mul add mul
      t sin 2 mul 4 u sin 2 mul add mul
      u cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=75](0,360)(80,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
    \parametricplotThreeD[yPlotpoints=1,linewidth=#2](0,360)(#1,#1){%
      u cos 2 mul 4 t sin 2 mul add mul
      u sin 2 mul 4 t sin 2 mul add mul
      t cos 4 mul
    }%
  \end{pspicture}%
}

\begin{animateinline}[poster=last,controls,palindrome]{12}%
  \multiframe{29}{iAngle=80+10, dLineWidth=2.9pt+-0.1pt}{%
    \torus{\iAngle}{\dLineWidth}%
  }%
\end{animateinline}%
\caption{}\label{fig:torus}
\end{figure}

Another inline example, Fig.~\ref{fig:lorenz}, is an animation of the Lorenz Attractor. The Lorenz Attractor is a three-dimensional parametric curve whose coordinates are obtained by integrating the set of three ordinary differential equations
\begin{align*}
  \frac{\mathrm{d}x}{\mathrm{d}t}& = \alpha (y-x)\\
  \frac{\mathrm{d}y}{\mathrm{d}t}& = x(\beta-z)-y\\
  \frac{\mathrm{d}z}{\mathrm{d}t}& = x y - \gamma z
\end{align*}
with respect to the independent parameter $t$. The shape of the attractor strongly depends on the values chosen for the coefficients $\alpha$, $\beta$ and $\gamma$ as well as on the initial conditions, that is, the coordinates $x_0$, $y_0$ and $z_0$ of the starting point of the curve. Here we use the values $\alpha=10$, $\beta=28$, $\gamma=8/3$ and the starting point $\mathbf{x}_0=(10,10,30)$.

The right hand sides of the equations above are defined in the macro \verb+\lorenz+ as algebraic expressions. The initial value problem is solved by the macro \verb+\pstODEsolve+ from the PSTricks package `pst-ode' and plotted by the macro \verb+\parametricplotThreeD+ from the PSTricks package `pst-3dplot'.

A timeline file, written on-the-fly, is used to assemble the curve segments frame by frame to the growing attractor which, in turn, is put on top of the $x$-$y$-$z$ coordinate system. After the attractor has been completed, the transparency stack is cleared. Then, transparencies containing the complete curve and the coordinate system seen from different viewpoints are put in a row to produce the animated fly-around.

\begin{figure}[t]
\centering
%
%Lorenz' set of differential equations
\def\lorenz{%
  10*(x[1]-x[0])        | %dx/dt
  x[0]*(28-x[2]) - x[1] | %dy/dt
  x[0]*x[1] - 8/3*x[2]    %dz/dt
}%
%
%write timeline file
\newwrite\OutFile%
\immediate\openout\OutFile=lorenz.tln%
\multido{\iLorenz=0+1}{101}{%
  \immediate\write\OutFile{::\iLorenz x0}%
}%
\immediate\write\OutFile{::c,101}%
\multido{\iLorenz=102+1}{89}{%
  \immediate\write\OutFile{::\iLorenz}%
}%
\immediate\closeout\OutFile%
%
\psset{unit=0.155,linewidth=0.5pt}%
\noindent\begin{animateinline}[
  timeline=lorenz.tln,
  controls,poster=last,
  begin={\begin{pspicture}(-39,-13)(39,60)},
  end={\end{pspicture}}
]{10}
  %coordinate axes
  \psset{Alpha=120,Beta=20}%
  \pstThreeDCoor[xMax=33,yMax=33,zMax=55,linecolor=black]%
\newframe
  %attractor segments
  \gdef\initCond{10 10 30}% initial condition
  \pstVerb{/lorenzXYZall {} def} %takes the whole attractor
  \multiframe{100}{rtZero=0+0.25,rtOne=0.25+0.25}{%
    %compute current attractor segment, store it in `lorenzXYZseg'
    \pstODEsolve[algebraic]{%
      lorenzXYZseg}{0 1 2}{\rtZero}{\rtOne}{26}{\initCond}{\lorenz}%
    %empty initial condition --> next \pstODEsolve continues
    \gdef\initCond{}%            from last state vector
    %append segment to the whole attractor stored in `lorenzXYZall'
    \pstVerb{%
      /lorenzXYZall [lorenzXYZall lorenzXYZseg] aload astore cvx def}
    %plot the current segment
    \listplotThreeD[plotstyle=line]{lorenzXYZseg}%
  }%
\newframe% required between two \multiframe
  %fly-around (whole attractor)
  \multiframe{90}{rAlpha=116+-4}{%
    \psset{Alpha=\rAlpha,Beta=20}%
    \pstThreeDCoor[xMax=33,yMax=33,zMax=55,linecolor=black]%
    \listplotThreeD[plotstyle=line]{lorenzXYZall}%
  }%
\end{animateinline}
\caption{}\label{fig:lorenz}
\end{figure}

%\small
\begin{lstlisting}
\documentclass{article}
\usepackage{multido}
\usepackage{pst-3dplot}
\usepackage{pst-ode}
\usepackage{animate}

\begin{document}

%Lorenz' set of differential equations
\def\lorenz{%
  10*(x[1]-x[0])        | %dx/dt
  x[0]*(28-x[2]) - x[1] | %dy/dt
  x[0]*x[1] - 8/3*x[2]    %dz/dt
}%
%
%write timeline file
\newwrite\OutFile%
\immediate\openout\OutFile=lorenz.tln%
\multido{\iLorenz=0+1}{101}{%
  \immediate\write\OutFile{::\iLorenz x0}%
}%
\immediate\write\OutFile{::c,101}%
\multido{\iLorenz=102+1}{89}{%
  \immediate\write\OutFile{::\iLorenz}%
}%
\immediate\closeout\OutFile%
%
\psset{unit=0.155,linewidth=0.5pt}%
\noindent\begin{animateinline}[
  timeline=lorenz.tln,
  controls,poster=last,
  begin={\begin{pspicture}(-36,-13)(36,55)},
  end={\end{pspicture}}
]{10}
  %coordinate axes
  \psset{Alpha=120,Beta=20}%
  \pstThreeDCoor[xMax=33,yMax=33,zMax=55,linecolor=black]%
\newframe
  %attractor segments
  \gdef\initCond{10 10 30}% initial condition
  \pstVerb{/lorenzXYZall {} def} %takes the whole attractor
  \multiframe{100}{rtZero=0+0.25,rtOne=0.25+0.25}{%
    %compute current attractor segment, store it in `lorenzXYZseg'
    \pstODEsolve[algebraic]{%
      lorenzXYZseg}{0 1 2}{\rtZero}{\rtOne}{26}{\initCond}{\lorenz}%
    %empty initial condition --> next \pstODEsolve continues
    \gdef\initCond{}%            from last state vector
    %append segment to the whole attractor stored in `lorenzXYZall'
    \pstVerb{%
      /lorenzXYZall [lorenzXYZall lorenzXYZseg] aload astore cvx def}%
    %plot the current segment
    \listplotThreeD[plotstyle=line]{lorenzXYZseg}%
  }%
\newframe% required between two \multiframe
  %fly-around (whole attractor)
  \multiframe{90}{rAlpha=116+-4}{%
    \psset{Alpha=\rAlpha,Beta=20}%
    \pstThreeDCoor[xMax=33,yMax=33,zMax=55,linecolor=black]%
    \listplotThreeD[plotstyle=line]{lorenzXYZall}%
  }%
\end{animateinline}

\end{document}
\end{lstlisting}
\normalsize

The last inline example in Fig.~\ref{fig:metronome} is a ticking metronome written by Manuel Luque~\cite{luque12}. The short clicking sound was embedded by means of the `media9' package. Whenever the pendulum reaches one of its reversal points, playback of the sound file is started using JavaScript. The JavaScript code was inserted at the corresponding frame specifications in a timeline file. Since the PSTricks macros for drawing the metronome body and the pendulum are quite long they have been moved into an external file, \verb+files/pstmetronome.tex+. Note that the sound can be heard only on Win and Mac platforms. Even then, mileage may vary. A dual core CPU may be necessary for fluent playback.
\begin{figure}[hb]
\centering
\begin{VerbatimOut}{files/pstmetronome.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% animated metronome
% this code is based to 99.9 percent on the work by Manuel Luque
% (pstricks.blogspot.com)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\makeatletter
\pst@addfams{pst-metronome}
\define@key[psset]{pst-metronome}{theta0}{\def\psk@oscmetronomethetai{#1 }}
\psset[pst-metronome]{theta0=45} % position initiale du metronome
\define@key[psset]{pst-metronome}{M}{\def\psk@oscmetronometM{#1 }}
\psset[pst-metronome]{M=25} % masse du disque en g
\define@key[psset]{pst-metronome}{m}{\def\psk@oscmetronometm{#1 }}
\psset[pst-metronome]{m=6} % masse du curseur en g
\define@key[psset]{pst-metronome}{r}{\def\psk@oscmetronomer{#1 }}
\psset[pst-metronome]{r=1} % rayon du disque en cm
\define@key[psset]{pst-metronome}{x}{\def\psk@oscmetronomex{#1 }}
\psset[pst-metronome]{x=8.4} % position du curseur en cm par rapport à l'axe
\define@key[psset]{pst-metronome}{d}{\def\psk@oscmetronomed{#1 }}
\psset[pst-metronome]{d=3.2} % distance de l'axe au centre du disque en cm
\define@key[psset]{pst-metronome}{dt}{\def\psk@oscmetronomedt{#1 }}
\psset[pst-metronome]{dt=0.01} % pas pour RK4
\define@key[psset]{pst-metronome}{nT}{\def\psk@oscmetronomenT{#1 }}
\psset[pst-metronome]{nT=1} % nombre de périodes représentées
%---- calculer theta(t) et thetapoint(t) --------
\def\psmetronome{\pst@object{psmetronome}}
\def\psmetronome@i{%
\begingroup%
\use@par%
  \begin@SpecialObj%
  \pstVerb{%
 /deg2rad {180 div 3.14159 mul} def
 /rad2deg {180 mul 3.14159 div} def
 /gp 9.8 def % pesanteur
 /radius \psk@oscmetronomer 1e-2 mul def % en m
 /OA \psk@oscmetronomed 1e-2 mul def % distance de l'axe au centre du disque en m
 /xC \psk@oscmetronomex 1e-2 mul def % position du curseur en m par rapport à l'axe
 /theta0 \psk@oscmetronomethetai def % en degrés
 /theta0rad theta0 deg2rad def % en radians
 /Md \psk@oscmetronometM 1e-3 mul def % en kg
 /mc \psk@oscmetronometm 1e-3 mul def % en kg
 /dt \psk@oscmetronomedt def
 /nT \psk@oscmetronomenT def
 % moment d'inertie du métronome
 % J=1/2M*R^2+M*a^2+m*x^2
 /Ji {0.5 Md mul radius dup mul mul Md OA dup mul mul add mc xC dup mul mul add} def
 /AT {4
      Ji
      gp Md OA mul mc xC mul sub mul
      div
      sqrt
      mul} def
 % Pour le calcul de la période
 % coefficients de l'approximation polynômiale du calcul
 % de l'intégrale elliptique
% coefficient pour le calcul de l'intégrale elliptique
        /m0 theta0 2 div sin def
        /m1 {1 m0 dup mul sub} def
        /m2 {m1 dup mul} def
        /m3 {m2 m1 mul} def
        /m4 {m2 dup mul} def
        /m_1 {1 m1 div} def
     /EllipticK {
        0.5
        0.12498593597 m1 mul add
        0.06880248576 m2 mul add
        0.03328355376 m3 mul add
        0.00441787012 m4 mul add
        m_1 ln mul
        1.38629436112 add
        0.09666344259 m1 mul add
        0.03590092383 m2 mul add
        0.03742563713 m3 mul add
        0.01451196212 m4 mul add
      } def
/Tm {AT EllipticK mul} def
% tableau des valeurs de theta(t)
    /W 0 def % vitesse angulaire
    /theta theta0 def
    /oscillateur {sin gp Md OA mul mc xC mul sub mul neg mul Ji div} def
    /j1 {W dt mul} def
    /k1 {theta oscillateur dt mul} def
    /j2 {W k1 2 div add dt mul} def
    /k2 {theta j1 2 div rad2deg add oscillateur dt mul} def
    /j3 {W k2 2 div add dt mul} def
    /k3 {theta j2 2 div rad2deg add oscillateur dt mul} def
    /j4 {W k3 add dt mul} def
    /k4 {theta j3 rad2deg add oscillateur dt mul} def
    /theta2 {theta j1 rad2deg 2 j2 rad2deg j3 rad2deg add mul add j4 rad2deg add 6 div add} def
/tabTheta [ % pour l'animation
    0 theta0 % date angle
dt dt Tm nT mul{ %
    theta2 %
    /W2 W k1 2 k2 k3 add mul add k4 add 6 div add def
    /theta theta2 def
    /W W2 def
    }  for
        ] def
/Nvaleurs tabTheta length 2 div cvi def
    /W 0 def % vitesse angulaire
    /theta theta0 def
/tabThetaGraph [ % pour le graphique theta(t)
    0 theta0  % date angle
0 dt Tm nT mul { % pop
    theta2 % 180 div 3.14159 mul
    /W2 W k1 2 k2 k3 add mul add k4 add 6 div add def
    /theta theta2 def
    /W W2 def
    }  for
        ] def
    /W 0 def % vitesse angulaire
    /theta theta0 def
/tabThetaPoint [ % pour le graphique thetapoint(t)
    0 0  % date angle
dt dt Tm nT mul { % pop
%    theta2 % 180 div 3.14159 mul
    /W2 W k1 2 k2 k3 add mul add k4 add 6 div add def
    W2
    /theta theta2 def
    /W W2 def
    }  for
        ] def
/tabXOSC [ % oscillations par min en fonction de x
0.5 0.1 12 {/xc exch def
 /xC xc 1e-2 mul def
 xc 60 Tm div % cvi
 } for
        ] def
/tabXbattements [ % battements par min en fonction de x
3 0.1 12 {/xc exch def
 /xC xc 1e-2 mul def
 xc 60 Tm div 2 mul % cvi
 } for
        ] def
% graduation T --> x
/tabXT [ % [T,x]
 40 1 220 {/batt exch def % battements
 /Tmetronome2 120 batt div dup mul def
 /A1 16 mc mul EllipticK dup mul mul def
 /B1 gp Tmetronome2 mul mc mul def
 /C1 gp Md mul OA mul Tmetronome2 mul neg
     8 Md mul radius dup mul mul 16 Md mul OA dup mul mul add EllipticK dup mul mul add def
 /Delta B1 dup mul 4 A1 mul C1 mul sub sqrt def
 /xC1 B1 neg Delta sub 2 div A1 div def
 /xC2 B1 neg Delta add 2 div A1 div def
 xC2 0 ge {/posC xC2 def}{/posC xC1 def} ifelse
 batt posC 1e2 mul
 } for
        ] def
/xT { % pour une valeur particulière battement -> position du curseur
    /batt exch def
    /Tmetronome2 120 batt div dup mul def
    /A1 16 mc mul EllipticK dup mul mul def
    /B1 gp Tmetronome2 mul mc mul def
    /C1 gp Md mul OA mul Tmetronome2 mul neg
     8 Md mul radius dup mul mul 16 Md mul OA dup mul mul add EllipticK dup mul mul add def
    /Delta B1 dup mul 4 A1 mul C1 mul sub sqrt def
    /xC1 B1 neg Delta sub 2 div A1 div def
    /xC2 B1 neg Delta add 2 div A1 div def
     xC2 0 ge {/posC xC2 def}{/posC xC1 def} ifelse
     posC 1e2 mul
 } def
/xC \psk@oscmetronomex 1e-2 mul def % position du curseur en m par rapport à l'axe
/Tm {AT EllipticK mul} def
  }%
  \end@SpecialObj%
\endgroup}
%
\def\psmetronomeA{\pst@object{psmetronomeA}}
\def\psmetronomeA@i{%
\begingroup%
\use@par%
  \begin@SpecialObj%
  \pstVerb{%
 /radius \psk@oscmetronomer 1e-2 mul def % en m
 /OA \psk@oscmetronomed 1e-2 mul def % distance de l'axe au centre du disque en m
 /xC \psk@oscmetronomex 1e-2 mul def % position du curseur en m par rapport à l'axe
  }%
\psframe[fillstyle=solid](! -0.075 \psk@oscmetronomed neg)(0.075,13)
\pscircle[fillstyle=solid,fillcolor={[rgb]{0.75 0.75 0.75}}](! 0 \psk@oscmetronomed neg){!radius 1e2 mul}
\pscircle[fillstyle=solid,linewidth=0.05](0,0){0.15}
\pscircle*[linecolor=red](0,0){0.05}
% curseur
\pspolygon[fillstyle=solid](! -0.25 \psk@oscmetronomex 0.5 sub)(! -0.5 \psk@oscmetronomex 0.5 add)(!-0.075 \psk@oscmetronomex 0.5 add)(!-0.075 \psk@oscmetronomex 0.5 sub)
\pspolygon[fillstyle=solid](! 0.25 \psk@oscmetronomex 0.5 sub)(! 0.5 \psk@oscmetronomex 0.5 add)(!0.075 \psk@oscmetronomex 0.5 add)(!0.075 \psk@oscmetronomex 0.5 sub)
\pspolygon[fillstyle=solid,fillcolor=gray](! -0.25 \psk@oscmetronomex 0.5 sub)(! -0.3 \psk@oscmetronomex 0.3 sub)(! -0.075 \psk@oscmetronomex 0.3 sub)(!-0.075 \psk@oscmetronomex 0.3 add)(!0.075 \psk@oscmetronomex 0.3 add)(!0.075 \psk@oscmetronomex 0.3 sub)(!0.3 \psk@oscmetronomex 0.3 sub)(!0.25 \psk@oscmetronomex 0.5 sub)
\pscircle[fillstyle=solid](!-0.125 \psk@oscmetronomex 0.4 sub){0.08}
\pscircle[fillstyle=solid](!0.125 \psk@oscmetronomex 0.4 sub){0.08}
% fin curseur
{\psset{linecolor=red}
\psline(!-.1 \psk@oscmetronomex)(!0.1 \psk@oscmetronomex)\psline(!0 \psk@oscmetronomex 0.1 sub)(!0 \psk@oscmetronomex 0.1 add)
\psline(! -.1 \psk@oscmetronomed neg)(!0.1 \psk@oscmetronomed neg)\psline(! 0 \psk@oscmetronomed neg 0.1 sub)(!0 \psk@oscmetronomed neg 0.1 add)}
\pnode(!0 \psk@oscmetronomex){C}% curseur
\pnode(! 0 \psk@oscmetronomed neg){D}% disque
%\pstextpath[c](0,-2ex){\psarcn[linestyle=none](D){1}{180}{0}}{\small\textsf{\textbf{m e t r o n o m e}}}
%\pstextpath[c](0,1ex){\psarc[linestyle=none](D){1}{180}{0}}{\small\textsf{\textbf{P S t r i c k s}}}
  \end@SpecialObj%
\endgroup}
\psmetronome%
\pstVerb{/tabTempos [40 42 44 46 48 50 52 54 46 58 60 63 66 69 72 76 80 84 88 92 96 100 104 108 112 116 120 126 132 138 144 152 160 168 176 184 192 200 208] def}%

\def\metronomebody{%
  \pspolygon[fillstyle=solid,linewidth=2\pslinewidth,linearc=0.5,fillcolor=yellow!30](-5,-4.5)(5,-4.5)(1,14)(-1,14)
  \psline(1.2,4.5)(1.2,12.5)
  \psline(-1.2,4.5)(-1.2,12.5)
  \multido{\i=0+2}{20}{%
     \pstVerb{/BATT tabTempos \i\space get def}
     \psline[linecolor=red](!1.2 BATT xT)(!0.7 BATT xT)
     \uput[r](!0.7 BATT xT){\psPrintValue[PSfont=Helvetica,fontscale=6]{BATT}}
  }%
  \multido{\i=1+2}{19}{%
     \pstVerb{/BATT tabTempos \i\space get def}
     \psline[linecolor=red](!-1.2 BATT xT)(!-0.7 BATT xT)
     \uput[r](!-1.3 BATT xT){\psPrintValue[PSfont=Helvetica,fontscale=6]{BATT}}}%
  \rput(!0 40 xT){\textsf{\tiny GRAVE}}%
  \rput(!0 46 xT){\textsf{\tiny LARGO}}%
  \rput(!0 52 xT){\textsf{\tiny LENTO}}%
  \rput(!0 58 xT){\textsf{\tiny ADAGIO}}%
  \rput(!0 60 xT){\textsf{\tiny LARGETTO}}%
  \rput(!0 66 xT){\textsf{\tiny ANDANTE}}%
  \rput(!0 76 xT){\textsf{\tiny ANDANTINO}}%
  \rput(!0 84 xT){\textsf{\tiny MODERATO}}%
  \rput(!0 108 xT){\textsf{\tiny ALLEGRETTO}}%
  \rput(!0 132 xT){\textsf{\tiny ALLEGRO}}%
  \rput(!0 160 xT){\textsf{\tiny VIVACE}}%
  \rput(!0 184 xT){\textsf{\tiny PRESTO}}%
  \rput(!0 200 xT){\textsf{\tiny PRESTISSIMO}}%
}

\def\pendulum#1{%
  \pstVerb{/iA #1\space def /date tabTheta iA get def /Theta tabTheta iA 1 add get def}%
  \rput{!Theta}{\psmetronomeA}%
}
\makeatother
\end{VerbatimOut}
\begin{VerbatimOut}{metro.txt}
::0x0,1 : annotRM['click'].callAS('play');
::2
::3
::4
::5
::6
::7
::8
::9
::10
::11
::12
::13
::14
::15
::16
::17
::18
::19
::20
::21
::22
::23
::24
::25
::26 : annotRM['click'].callAS('play');
\end{VerbatimOut}
%loading metronome macros from external file
\input{files/pstmetronome}
%sound inclusion: click.mp3
\makebox[0pt][r]{\includemedia[
  width=1ex,height=1ex,
  label=click,
  addresource=click.mp3,
  activate=pageopen,transparent,noplaybutton,
  flashvars={source=click.mp3&hideBar=true}
]{}{APlayer.swf}}%
%animated metronome
\begin{animateinline}[
  controls,
  width=0.7\linewidth,
  palindrome,
  begin={\begin{pspicture}(-9.5,-5)(9.5,15)},
  end={\end{pspicture}},
  timeline=metro.txt
]{25}
  %metronome without pendulum
  \metronomebody
\newframe
  %half period of pendulum swing (26 frames)
  \multiframe{26}{i=0+4}{
    \pendulum{\i}
  }
\end{animateinline}
\caption{}\label{fig:metronome}
\end{figure}
%\small
\begin{lstlisting}
\documentclass[12pt]{article}
\usepackage{pstricks,pst-node,pst-plot,pst-tools,pst-text}
\usepackage{animate}
\usepackage{media9}

%writing timeline to external file
\begin{filecontents}{metro.txt}
::0x0,1 : annotRM['click'].callAS('play');
::2
::3
::4
::5
::6
::7
::8
::9
::10
::11
::12
::13
::14
::15
::16
::17
::18
::19
::20
::21
::22
::23
::24
::25
::26 : annotRM['click'].callAS('play');
\end{filecontents}

\begin{document}

\begin{center}
  %loading metronome macros from external file
  \input{files/pstmetronome}
  %
  %sound inclusion: click.mp3
  \makebox[0pt][r]{\includemedia[
    width=1ex,height=1ex,
    label=click,
    addresource=click.mp3,
    activate=pageopen,transparent,noplaybutton,
    flashvars={source=click.mp3&hideBar=true}
  ]{}{APlayer.swf}}%
  %
  %animated metronome
  \begin{animateinline}[
    controls,
    width=0.7\linewidth,
    palindrome,
    begin={\begin{pspicture}(-9.5,-5)(9.5,15)},
    end={\end{pspicture}},
    timeline=metro.txt
  ]{25}
    %metronome without pendulum
    \metronomebody
  \newframe
    %half period of pendulum swing (26 frames)
    \multiframe{26}{i=0+4}{
      \pendulum{\i}
    }
  \end{animateinline}
\end{center}

\end{document}
\end{lstlisting}

\section{Animated SVG}
Thanks to Martin Gieseking's \verb+dvisvgm+ utility~\cite{dvisvgm} that ships with all major \TeX{} distributions, package `animate' can produce self-contained animated SVG, with all the bits and pieces already included that are necessary to run in modern Web browsers as standalone files or as embedded objects within a Web page made of HTML. Animations have the same look and usability, including optional control buttons, as if they were embedded in a PDF document. Animated SVG even work on mobile devices.

As \verb+dvisvgm+ is linked against the Ghostscript library, it can parse and convert embedded PostScript to inline SVG code. It is therefore compatible with the popular TikZ and PSTricks \LaTeX{} packages.
 
SVG is a single-page graphics format. Therefore, it is recommended to produce documents with a single animation per file or page. Thereafter, \verb+dvisvgm+ converts every page of the DVI input to a standalone animated SVG file. You may want to use the `standalone' document class for creating standalone SVG animations. Pass `\verb+dvisvgm+' as a global document class option. In this way, it gets conveyed to `animate' and other packages to be loaded, such as `graphicx' or TikZ.

The following code may serve as a template for generating standalone animated SVG:
\begin{lstlisting}
\documentclass[dvisvgm]{standalone}

%\usepackage{xcolor}
%\pagecolor{white} % opaque background with solid colour

%\usepackage{pstricks} % enable as needed
%\usepackage{tikz}

\usepackage{animate}
\usepackage{graphicx}

\begin{document}
%
% \animategraphics{..}{...}{...}{...}
%
% or  
%  
% \begin{animateinline}{..} ... \end{animateinline} 
%
\end{document}
\end{lstlisting}
Note that when animating external graphics with \verb+\animategraphics+, only PDF and PostScript (EPS, PS, MPS) files are converted to inline SVG code; files in other formats (SVG, PNG, JPEG) remain external and must be bundled with the final SVG output. Thus, for obtaining self-contained SVG, it is recommended to convert PNG, JPEG and SVG files to PDF or PostScript first. Also note that PostScript files must have all required fonts embedded. This is not always the case for \MP-generated PostScript. Here, embedding of fonts is ensured by putting `\verb+prologues := 3;+' into the header of the \MP{} input.

Use one of
\begin{verbatim}
latex
platex
dvilualatex
xelatex -no-pdf
\end{verbatim}
to produce DVI or XDV output from the \LaTeX{} source. After this, SVG is obtained by running
%\begin{verbatim}
%dvisvgm --font-format=woff --exact --zoom=-1 --page=1,- --optimize ...
%\end{verbatim}
\begin{verbatim}
dvisvgm --font-format=woff --exact --zoom=-1 --page=1,- ...
\end{verbatim}
on the intermediate DVI or XDV file.

Option `\verb+--font-format=woff+' (or `\verb+--font-format=woff2+') prompts \verb+dvisvgm+ to embed document fonts in a format that is understood by Web browsers. It ensures that typeset text looks as in normal PDF output.

Option `\verb+--exact+' tells \verb+dvisvgm+ to calculate exact bounding boxes around font glyphs. This avoids clipping of glyphs in the SVG output, as glyphs usually tend to be slightly bigger than their boxes defined in the font files.

The purpose of `\verb+--zoom=-1+' is to produce responsive SVG. If embedded in a Web page, this kind of SVG will automatically scale to fill up the available space of its surrounding container, usually an \verb+<object>+ tag (see below). If viewed standalone in a Web browser, a responsive SVG fills up the complete browser tab.

By default, \verb+dvisvgm+ processes only the very first page of the input file. To convert multipage DVI/XDV with several animations, add option `\verb+--page=1,-+'.

%With option `\verb+--optimize+', \verb+dvisvgm+ applies several optimizations to reduce the output file size.

As SVG derives from XML it is not known to be particularly economical in terms of file size. Compressed SVG, with file extension `\verb+svgz+', shortens download times and is supported by most Web browsers. It can be generated by adding option `\verb+-z+'. Also, option `\verb+--precision=1+' may be used to reduce the SVG file size. It limits the precision of floating point numbers, such as coordinates, to one decimal figure. Sometimes, animations may behave stangely after applying this option. Then, of course, it should be omitted.

The recommended way to include animated SVG into HTML is to use the \verb+<object>+ tag. The \verb+<img>+ tag does not work here, as it ignores the embedded JavaScript. However, it may still be used as fallback. Also, it allows for search engine indexing, if desired:
\begin{lstlisting}
<object type="image/svg+xml" data="animatedImage.svg">
  <!-- optional (increases loading time):
       fallback & search engine indexing -->
  <img src="animatedImage.svg" />
</object>
\end{lstlisting}

In \TeX4ht documents, the whole \verb+<object>...</object>+ tag can be inserted by wrapping it in a \verb+\HCode{...}+ command.

\section{Bugs}\label{sect:bugs}
\begin{itemize}
  \item The maximum frame rate that can actually be achieved largely depends on the complexity of the graphics and on the available hardware. In Acrobat Reader, you might want to experiment with the 2D graphical hardware acceleration feature. Go to menu `Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Page Display' $\rightarrow$ `Rendering' to see whether hardware acceleration is available. A 2D GPU acceleration check box will be visible if a supported video card has been detected. Also, enabling or disabling the page cache (`Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Page Display' $\rightarrow$ `Rendering' $\rightarrow$ `Use page cache') may affect the rendering performance.

  \item Animated SVG is best viewed in Web browsers that are based on the Blink rendering engine. The most prominent representatives are Chrome, its open-source base Chromium and Opera. Unfortunately, Firefox is very slow.

  \item The \verb+dvips+ option `\verb+-Ppdf+' should be avoided entirely or followed by something like `\verb+-D 1200+' on the command line in order to set a sensible DVI resolution. This does \emph{not} degrade the output quality! The configuration file `config.pdf' loaded by option `\verb+-Ppdf+' specifies an excessively high DVI resolution that will be passed on to the final PDF. Eventually, Acrobat Reader gets confused and will not display the frames within the animation widget.

  \item Animations do not work if the PDF was produced with Ghostscript versions older than 9.15.

  \item If the `\verb+animateinline+' environment is used in a right-to-left typesetting context (RTL) and using the (pdf)\LaTeX{} and \XeLaTeX{} engines, every frame's content should be enclosed in a pair of \verb+\beginR+ and \verb+\endR+ commands in order to correctly typeset RTL text contained therein. This can be conveniently done by means of the `\verb+begin+' and `\verb+end+' \hyperlink{beginend}{options} of the `\verb+animateinline+' environment.

%  \item If the \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller route is being taken, make sure that the original graphics size (i.\,e. not scaled by any of the `{\tt scale}', `{\tt width}', `{\tt height}' or `{\tt totalheight}' options) does not exceed the page size of the final document. During PS to PDF conversion every graphic of the animation is temporarily moved to the upper left page corner. Those parts of the graphics that do not fit onto the document page will be clipped in the resulting PDF. Fortunately, graphics files for building animations may be resized easily to fit into a given bounding box by means of the `{\tt epsffit}' command line tool:
%
%\quad{\tt epsffit -c <llx> <lly> <urx> <ury> infile.eps outfile.eps}
%
%{\tt <llx> <lly> <urx> <ury>} are the bounding box coordinates of the target document. They can be determined using Ghostscript. For a document named `document.ps' the command line is
%
%\quad{\tt gs -dNOPAUSE -q -dBATCH -sDEVICE=bbox document.ps}
%
%Note that the name of the Ghostscript executable may vary between operating systems (e.\,g. `{\tt gswin32c.exe}' on Win/DOS).

  \item\hypertarget{dest:mem}{} Animations with complex graphics and/or many frames may cause \LaTeX{} to fail with a `\verb+TeX capacity exceeded+' error. The following steps should fix most of the memory related problems.

  MiK\TeX:
  \begin{enumerate}
    \item Open a DOS command prompt window (execute `cmd.exe' via `Start' $\rightarrow$ `Run').
    \item\label{item:firststep} At the DOS prompt, enter\\
    {\tt initexmf -{}-edit-config-file=latex}
    \item Type\\
    {\tt main\_memory=12000000}\\
    into the editor window that opens, save the file and quit the editor.
    \item\label{item:laststep} To rebuild the format, enter\\
    {\tt initexmf -{}-dump=latex}
    \item Repeat steps \ref{item:firststep}--\ref{item:laststep} with config files {\tt pdflatex} and {\tt xelatex}
  \end{enumerate}

  \TeX\ Live:
  \begin{enumerate}
    \item Find the configuration file `texmf.cnf' by means of\\
    {\tt kpsewhich texmf.cnf}\\
    at the shell prompt in a terminal.
    \item As Root, open the file in your favourite text editor, scroll to the\\`{\tt main\_memory}' entry and change it to the value given above; save and quit.
    \item Rebuild the formats by\\
    {\tt fmtutil-sys -{}-byfmt latex}\\
    {\tt fmtutil-sys -{}-byfmt pdflatex}\\
    {\tt fmtutil-sys -{}-byfmt xelatex}
  \end{enumerate}

%  \item If a PDF containing animations is post-processed using tools like PDFtk to split the document into separate files, then animations in the output documents may not work.

  \item PDFs with animations cannot be embedded (via {\tt\string\includegraphics},\\ {\tt\string\includepdf}) into other documents as the animation capability gets lost.

  \item Animations should not be placed on \emph{multilayered} slides, also known as overlays, created with presentation making classes such as Beamer or Powerdot. Those document classes turn overlays into separate PDF pages and re-insert the animation on every page thus produced. The animations are independent from each other and do not share the current playing state, such as frame number, playing speed and direction. Therefore, put animations on flat slides only; slides without animations may still have overlays, of course. On \href{https://tex.stackexchange.com/a/385209}{\TeX.SE}~\cite{texsx}, a method is suggested for placing an animation on a slide with overlays. It makes use of the programming interface introduced in Sect.~\ref{sect:api}, p.~\pageref{sect:api}.
\end{itemize}

\section{Acknowledgements}
I would like to thank François Lafont who discovered quite a few bugs and made many suggestions that helped to improve the functionality of the package. Many thanks to Jin-Hwan Cho, the developer of \verb+dvipdfmx+, for contributing the \verb+dvipdfmx+ specific code, and to Walter Scott for proof-reading the documentation.

\enlargethispage{4ex}
\begin{thebibliography}{8}
\bibitem{chupin} Chupin, M.: \emph{Syracuse MetaPost/Animations.} URL: \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{http://melusine.eu.org/}} \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{syracuse/metapost/animations/chupin/?idsec=scara}}
\bibitem{dvisvgm} \emph{dvisvgm: A fast DVI to SVG converter} URL: \url{http://dvisvgm.de}
\bibitem{gilg05} Gilg, J.: PDF-Animationen. In: \emph{Die \TeX nische Kom\"odie}, Issue 4, 2005, pp.~30--37
%\bibitem{hol} Holeček, J.: \emph{Animations in a pdf\TeX-generated PDF}. URL: \url{http://www.fi.muni.cz/~xholecek/tex/pdfanim.xhtml}
\bibitem{hol} Holeček, J.; Sojka, P.: Animations in pdf\TeX-generated PDF. In: \emph{\TeX, XML, and Digital Typography}, Springer, 2004, pp.~179--191. doi:10.1007/978-3-540-27773-6\textunderscore14
\bibitem{luque12} Luque, M.: \emph{PSTricks : applications.} URL: \url{http://pstricks.blogspot.com}
\bibitem{media4svg} \emph{The media4svg Package}. URL: \url{http://www.ctan.org/pkg/media4svg}
\bibitem{media9} \emph{The media9 Package}. URL: \url{http://www.ctan.org/pkg/media9}
\bibitem{texsx} \emph{Beamer: animate package and overlay}. URL: \href{https://tex.stackexchange.com/a/385209}{\url{https://tex.stackexchange.com}}\\ \href{https://tex.stackexchange.com/a/385209}{\url{/a/385209}}
\end{thebibliography}

\end{document}