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.zip
8    /oem/media/bootanimation.zip
9
10## zipfile layout
11
12The `bootanimation.zip` archive file includes:
13
14    desc.txt - a text file
15    part0  \
16    part1   \  directories full of PNG frames
17    ...     /
18    partN  /
19
20## desc.txt format
21
22The first line defines the general parameters of the animation:
23
24    WIDTH HEIGHT FPS [PROGRESS]
25
26  * **WIDTH:** animation width (pixels)
27  * **HEIGHT:** animation height (pixels)
28  * **FPS:** frames per second, e.g. 60
29  * **PROGRESS:** whether to show a progress percentage on the last part
30      + The percentage will be displayed with an x-coordinate of 'c', and a
31        y-coordinate set to 1/3 of the animation height.
32
33Next, provide an optional line for dynamic coloring attributes, should dynamic coloring be used.
34See the dyanmic coloring section for format details. Skip if you don't use dynamic coloring.
35
36It is followed by a number of rows of the form:
37
38    TYPE COUNT PAUSE PATH [FADE [#RGBHEX [CLOCK1 [CLOCK2]]]]
39
40  * **TYPE:** a single char indicating what type of animation segment this is:
41      + `p` -- this part will play unless interrupted by the end of the boot
42      + `c` -- this part will play to completion, no matter what
43      + `f` -- same as `p` but in addition the specified number of frames is being faded out while
44        continue playing. Only the first interrupted `f` part is faded out, other subsequent `f`
45        parts are skipped
46  * **COUNT:** how many times to play the animation, or 0 to loop forever until boot is complete
47  * **PAUSE:** number of FRAMES to delay after this part ends
48  * **PATH:** directory in which to find the frames for this part (e.g. `part0`)
49  * **FADE:** _(ONLY FOR `f` TYPE)_ number of frames to fade out when interrupted where `0` means
50              _immediately_ which makes `f ... 0` behave like `p` and doesn't count it as a fading
51              part
52  * **RGBHEX:** _(OPTIONAL)_ a background color, specified as `#RRGGBB`
53  * **CLOCK1, CLOCK2:** _(OPTIONAL)_ the coordinates at which to draw the current time (for watches):
54      + If only `CLOCK1` is provided it is the y-coordinate of the clock and the x-coordinate
55        defaults to `c`
56      + If both `CLOCK1` and `CLOCK2` are provided then `CLOCK1` is the x-coordinate and `CLOCK2` is
57        the y-coodinate
58      + Values can be either a positive integer, a negative integer, or `c`
59          - `c` -- will centre the text
60          - `n` -- will position the text n pixels from the start; left edge for x-axis, bottom edge
61            for y-axis
62          - `-n` -- will position the text n pixels from the end; right edge for x-axis, top edge
63            for y-axis
64          - Examples:
65              * `-24` or `c -24` will position the text 24 pixels from the top of the screen,
66                centred horizontally
67              * `16 c` will position the text 16 pixels from the left of the screen, centred
68                vertically
69              * `-32 32` will position the text such that the bottom right corner is 32 pixels above
70                and 32 pixels left of the edges of the screen
71
72There is also a special TYPE, `$SYSTEM`, that loads `/system/media/bootanimation.zip`
73and plays that.
74
75## clock_font.png
76
77The file used to draw the time on top of the boot animation. The font format is as follows:
78  * The file specifies glyphs for the ascii characters 32-127 (0x20-0x7F), both regular weight and
79    bold weight.
80  * The image is divided into a grid of characters
81  * There are 16 columns and 6 rows
82  * Each row is divided in half: regular weight glyphs on the top half, bold glyphs on the bottom
83  * For a NxM image each character glyph will be N/16 pixels wide and M/(12*2) pixels high
84
85## progress_font.png
86
87The file used to draw the boot progress in percentage on top of the boot animation. The font format
88follows the same specification as the one described for clock_font.png.
89
90## loading and playing frames
91
92Each part is scanned and loaded directly from the zip archive. Within a part directory, every file
93(except `trim.txt` and `audio.wav`; see next sections) is expected to be a PNG file that represents
94one frame in that part (at the specified resolution). For this reason it is important that frames be
95named sequentially (e.g. `part000.png`, `part001.png`, ...) and added to the zip archive in that
96order.
97
98## trim.txt
99
100To save on memory, textures may be trimmed by their background color.  trim.txt sequentially lists
101the trim output for each frame in its directory, so the frames may be properly positioned.
102Output should be of the form: `WxH+X+Y`. Example:
103
104    713x165+388+914
105    708x152+388+912
106    707x139+388+911
107    649x92+388+910
108
109If the file is not present, each frame is assumed to be the same size as the animation.
110
111## audio.wav
112
113Each part may optionally play a `wav` sample when it starts. To enable this, add a file
114with the name `audio.wav` in the part directory.
115
116## exiting
117
118The system will end the boot animation (first completing any incomplete or even entirely unplayed
119parts that are of type `c`) when the system is finished booting. (This is accomplished by setting
120the system property `service.bootanim.exit` to a nonzero string.)
121
122## protips
123
124### PNG compression
125
126Use `zopflipng` if you have it, otherwise `pngcrush` will do. e.g.:
127
128    for fn in *.png ; do
129        zopflipng -m ${fn} ${fn}.new && mv -f ${fn}.new ${fn}
130        # or: pngcrush -q ....
131    done
132
133Some animations benefit from being reduced to 256 colors:
134
135    pngquant --force --ext .png *.png
136    # alternatively: mogrify -colors 256 anim-tmp/*/*.png
137
138### creating the ZIP archive
139
140    cd <path-to-pieces>
141    zip -0qry -i \*.txt \*.png \*.wav @ ../bootanimation.zip *.txt part*
142
143Note that the ZIP archive is not actually compressed! The PNG files are already as compressed
144as they can reasonably get, and there is unlikely to be any redundancy between files.
145
146### Dynamic coloring
147
148Dynamic coloring is a render mode that draws the boot animation using a color transition.
149In this mode, instead of directly rendering the PNG images, it treats the R, G, B, A channels
150of input images as area masks of dynamic colors, which interpolates between start and end colors
151based on animation progression.
152
153To enable it, add the following line as the second line of desc.txt:
154
155    dynamic_colors PATH #RGBHEX1 #RGBHEX2 #RGBHEX3 #RGBHEX4
156
157  * **PATH:** file path of the part to apply dynamic color transition to.
158    Any part before this part will be rendered in the start colors.
159    Any part after will be rendered in the end colors.
160  * **RGBHEX1:** the first start color (masked by the R channel), specified as `#RRGGBB`.
161  * **RGBHEX2:** the second start color (masked by the G channel), specified as `#RRGGBB`.
162  * **RGBHEX3:** the third start color (masked by the B channel), specified as `#RRGGBB`.
163  * **RGBHEX4:** the forth start color (masked by the A channel), specified as `#RRGGBB`.
164
165The end colors will be read from the following system properties:
166
167  * persist.bootanim.color1
168  * persist.bootanim.color2
169  * persist.bootanim.color3
170  * persist.bootanim.color4
171
172When missing, the end colors will default to the start colors, effectively producing no color
173transition.
174
175Prepare your PNG images so that the R, G, B, A channels indicates the areas to draw color1,
176color2, color3 and color4 respectively.
177