Deciphering Android's bootanimation.zip desc.txt
Update (May, 2017): AOSP has written a FORMAT.md document that is more up-to-date than this article. It will likely be the living document for detailing how animation works in Android. This article is kept for posterity.
So you're an Android wizz and want to further customize your wicked Android experience. You've perused the plethora of custom boot screen animations and nothing tickles your fancy, or you've installed a popular ROM like CyanogenMod and you're just not happy with it.
You've got your animation ready, you've exported it as a series of sequenctial PNGs, and you're ready to go!
Alas, what the #@$!&@ is the
desc.txt used for? And why the many parts folders? This article seeks to answer that question.
Straight to the source
For the expertly technical, you can read the BootAnimation.cpp source code to see exactly how Android boot animations work. Because things change in major releases of Android, not all
desc.txt files are created equal.
For example, did you know boot animations now support playing sound as of Android Lollipop (5.0–5.1.1)?
Boot animations are a series of PNG images, loaded & displayed one after the other, to create the illusion of video. This is a smaller memory & CPU footprint than decoding an actual video file with codecs.
Some boot animations have intros, a main loop, and then an outro. This is what the
part* folders &
desc.txt allow. You don't have to have intros & outros, but it make for a much more polished effect. The above video example of CopperheadOS's boot animation (made by yours truly) is comprised of an intro, main loop, and outro.
You group your PNGs into folders and specify, for each part:
- How many times the PNGs should loop before the next sequence plays
- How long should the last frame pause before continuing
- And if Android is allow to abort the animation early if the OS is fully loaded
.zip file (which cannot be compressed, it's meant to just be a blob!) should be laid out in the following fashion:
desc.txt part0/ 0000.png 0001.png 0002.png ... part1/ 0000.png 0001.png 0002.png ... ...
You need a minimum of one
part0 folder, containing your parts. It appears there's no programmed limit to how many PNGs per part, and how many parts in total. Note that because they're PNG images, you can easily have a very large boot animation. I recommend keeping it under 20MB.
Anatomy of a
Note what you can define here is limited by the version of Android. Not all versions support the
c part type. That was introduced in Android Jelly Bean (4.1–4.3.1)
700 420 30 c 1 15 part0 000000 c 0 0 part1 FF0000 c 1 30 part2 0000FF
[width] [height] [frames per second]
So in our above example:
700is the width of the PNGs
420is the height of the PNGs
30is the frames per second. I've seen
You want to define each part on its own line:
[type] [loop count] [pause] [path] [bg colour (optional)]
You can have transparent PNGs that will show a background colour but almost all animations I see have a matte, full black background in the PNGs and the optional colour section absent in the
[type] with value
c is only supported in Android Jelly Bean or later. It must be
p for older Android versions.
Second Line (The Intro)
cis the "type". If it is
cand the OS has finished loading halfway through the sequence loop, then it will finish the loop & exit gracefully. If it is
pthen the animation will abort mid-sequence if the OS has loaded. Unless you have an older Android OS, you typically want
cfor a refined animation.
1is the loop count. This means play once then proceed to the next sequence.
15is the "pausing" in frames of the last frame in the sequence before going to the next sequence. So in this example it's pausing 0.5 seconds because
15is half of
part0is the path to the collection of PNGs to use in this part
000000is the background colour in hex. This value is full black and the default colour. You can define a desc.txt with this entry absent (and most do).
Third Line (The Main Loop)
cis still used, because this is where the OS will eventually finish loading. We want a graceful exit to the outro.
0is a special loop count. It means "loop forever". This part is where the OS will load and exit. Because we chose
cit will gracefully exit to the end of the animation. If
pwas chosen, this is where the animation would abort & exit.
0means no delay. Duh.
part1is the path to the collection of PNGs to use in this part
FF0000means a red background for this part
Fourth Line (The Outro)
cis still used, because otherwise the outro would abort.
1is used because, thanks to
c, the outro sequence must play even if the OS has loaded; so we play it once. If you chose
pfor the outro but
cfor prior parts, it'd exit immediately without playing. If you chose
0here, the boot animation would loop forever and never stop!
30means pause a final second before showing the OS. Maybe your outro is fading to black so your final frame is a black screen.
part2is the path to the collection of PNGs to use in this part
0000FFmeans a blue background for this part
And there you have it!
I hope you found this useful. There's a lot of misinformation and incorrect forum posts out there detailing how to properly write a
Feel free to leave a comment if you have any questions and I'll try to answer them to the best of my ability.