1# bootanimation format
2
3## zipfile paths
4
5The system selects a boot animation zipfile from the following locations, in order:
6
7    /system/media/bootanimation-encrypted.zip (if getprop("vold.decrypt") = '1')
8    /system/media/bootanimation.zip
9    /oem/media/bootanimation.zip
10
11## zipfile layout
12
13The `bootanimation.zip` archive file includes:
14
15    desc.txt - a text file
16    part0  \
17    part1   \  directories full of PNG frames
18    ...     /
19    partN  /
20
21## desc.txt format
22
23The first line defines the general parameters of the animation:
24
25    WIDTH HEIGHT FPS
26
27  * **WIDTH:** animation width (pixels)
28  * **HEIGHT:** animation height (pixels)
29  * **FPS:** frames per second, e.g. 60
30
31It is followed by a number of rows of the form:
32
33    TYPE COUNT PAUSE PATH [#RGBHEX [CLOCK1 [CLOCK2]]]
34
35  * **TYPE:** a single char indicating what type of animation segment this is:
36      + `p` -- this part will play unless interrupted by the end of the boot
37      + `c` -- this part will play to completion, no matter what
38  * **COUNT:** how many times to play the animation, or 0 to loop forever until boot is complete
39  * **PAUSE:** number of FRAMES to delay after this part ends
40  * **PATH:** directory in which to find the frames for this part (e.g. `part0`)
41  * **RGBHEX:** _(OPTIONAL)_ a background color, specified as `#RRGGBB`
42  * **CLOCK1, CLOCK2:** _(OPTIONAL)_ the coordinates at which to draw the current time (for watches):
43      + If only `CLOCK1` is provided it is the y-coordinate of the clock and the x-coordinate
44        defaults to `c`
45      + If both `CLOCK1` and `CLOCK2` are provided then `CLOCK1` is the x-coordinate and `CLOCK2` is
46        the y-coodinate
47      + Values can be either a positive integer, a negative integer, or `c`
48          - `c` -- will centre the text
49          - `n` -- will position the text n pixels from the start; left edge for x-axis, bottom edge
50            for y-axis
51          - `-n` -- will position the text n pixels from the end; right edge for x-axis, top edge
52            for y-axis
53          - Examples:
54              * `-24` or `c -24` will position the text 24 pixels from the top of the screen,
55                centred horizontally
56              * `16 c` will position the text 16 pixels from the left of the screen, centred
57                vertically
58              * `-32 32` will position the text such that the bottom right corner is 32 pixels above
59                and 32 pixels left of the edges of the screen
60
61There is also a special TYPE, `$SYSTEM`, that loads `/system/media/bootanimation.zip`
62and plays that.
63
64## clock_font.png
65
66The file used to draw the time on top of the boot animation. The font format is as follows:
67  * The file specifies glyphs for the ascii characters 32-127 (0x20-0x7F), both regular weight and
68    bold weight.
69  * The image is divided into a grid of characters
70  * There are 16 columns and 6 rows
71  * Each row is divided in half: regular weight glyphs on the top half, bold glyphs on the bottom
72  * For a NxM image each character glyph will be N/16 pixels wide and M/(12*2) pixels high
73
74## loading and playing frames
75
76Each part is scanned and loaded directly from the zip archive. Within a part directory, every file
77(except `trim.txt` and `audio.wav`; see next sections) is expected to be a PNG file that represents
78one frame in that part (at the specified resolution). For this reason it is important that frames be
79named sequentially (e.g. `part000.png`, `part001.png`, ...) and added to the zip archive in that
80order.
81
82## trim.txt
83
84To save on memory, textures may be trimmed by their background color.  trim.txt sequentially lists
85the trim output for each frame in its directory, so the frames may be properly positioned.
86Output should be of the form: `WxH+X+Y`. Example:
87
88    713x165+388+914
89    708x152+388+912
90    707x139+388+911
91    649x92+388+910
92
93If the file is not present, each frame is assumed to be the same size as the animation.
94
95## audio.wav
96
97Each part may optionally play a `wav` sample when it starts. To enable this, add a file
98with the name `audio.wav` in the part directory.
99
100## exiting
101
102The system will end the boot animation (first completing any incomplete or even entirely unplayed
103parts that are of type `c`) when the system is finished booting. (This is accomplished by setting
104the system property `service.bootanim.exit` to a nonzero string.)
105
106## protips
107
108### PNG compression
109
110Use `zopflipng` if you have it, otherwise `pngcrush` will do. e.g.:
111
112    for fn in *.png ; do
113        zopflipng -m ${fn}s ${fn}s.new && mv -f ${fn}s.new ${fn}
114        # or: pngcrush -q ....
115    done
116
117Some animations benefit from being reduced to 256 colors:
118
119    pngquant --force --ext .png *.png
120    # alternatively: mogrify -colors 256 anim-tmp/*/*.png
121
122### creating the ZIP archive
123
124    cd <path-to-pieces>
125    zip -0qry -i \*.txt \*.png \*.wav @ ../bootanimation.zip *.txt part*
126
127Note that the ZIP archive is not actually compressed! The PNG files are already as compressed
128as they can reasonably get, and there is unlikely to be any redundancy between files.
129