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