cmds/bootanimation/FORMAT.md

   1 # bootanimation format
   2
   3 ## zipfile paths
   4
   5 The 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
  13 The `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
  23 The 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
  31 It is followed by a number of rows of the form:
  32
  33     TYPE COUNT PAUSE PATH [#RGBHEX CLOCK]
  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   * **CLOCK:** _(OPTIONAL)_ the y-coordinate at which to draw the current time (for watches)
  43
  44 There is also a special TYPE, `$SYSTEM`, that loads `/system/media/bootanimation.zip`
  45 and plays that.
  46
  47 ## loading and playing frames
  48
  49 Each part is scanned and loaded directly from the zip archive. Within a part directory, every file
  50 (except `trim.txt` and `audio.wav`; see next sections) is expected to be a PNG file that represents
  51 one frame in that part (at the specified resolution). For this reason it is important that frames be
  52 named sequentially (e.g. `part000.png`, `part001.png`, ...) and added to the zip archive in that
  53 order.
  54
  55 ## trim.txt
  56
  57 To save on memory, textures may be trimmed by their background color.  trim.txt sequentially lists
  58 the trim output for each frame in its directory, so the frames may be properly positioned.
  59 Output should be of the form: `WxH+X+Y`. Example:
  60
  61     713x165+388+914
  62     708x152+388+912
  63     707x139+388+911
  64     649x92+388+910
  65
  66 If the file is not present, each frame is assumed to be the same size as the animation.
  67
  68 ## audio.wav
  69
  70 Each part may optionally play a `wav` sample when it starts. To enable this, add a file
  71 with the name `audio.wav` in the part directory.
  72
  73 ## exiting
  74
  75 The system will end the boot animation (first completing any incomplete or even entirely unplayed
  76 parts that are of type `c`) when the system is finished booting. (This is accomplished by setting
  77 the system property `service.bootanim.exit` to a nonzero string.)
  78
  79 ## protips
  80
  81 ### PNG compression
  82
  83 Use `zopflipng` if you have it, otherwise `pngcrush` will do. e.g.:
  84
  85     for fn in *.png ; do
  86         zopflipng -m ${fn}s ${fn}s.new && mv -f ${fn}s.new ${fn}
  87         # or: pngcrush -q ....
  88     done
  89
  90 Some animations benefit from being reduced to 256 colors:
  91
  92     pngquant --force --ext .png *.png
  93     # alternatively: mogrify -colors 256 anim-tmp/*/*.png
  94
  95 ### creating the ZIP archive
  96
  97     cd <path-to-pieces>
  98     zip -0qry -i \*.txt \*.png \*.wav @ ../bootanimation.zip *.txt part*
  99
 100 Note that the ZIP archive is not actually compressed! The PNG files are already as compressed
 101 as they can reasonably get, and there is unlikely to be any redundancy between files.