Deciphering Android's bootanimation.zip desc.txt

by Justin Bull

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)?

Basic Premise

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:

  1. How many times the PNGs should loop before the next sequence plays
  2. How long should the last frame pause before continuing
  3. And if Android is allow to abort the animation early if the OS is fully loaded

Your .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 desc.txt file

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)

Our example desc.txt

700 420 30  
c 1 15 part0 000000  
c 0 0 part1 FF0000  
c 1 30 part2 0000FF

Top line

[width] [height] [frames per second]

So in our above example:

  • 700 is the width of the PNGs
  • 420 is the height of the PNGs
  • 30 is the frames per second. I've seen 60, 30, and 10 used here.

Subsequent lines

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 desc.txt.

Note: [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)

  • c is the "type". If it is c and the OS has finished loading halfway through the sequence loop, then it will finish the loop & exit gracefully. If it is p then the animation will abort mid-sequence if the OS has loaded. Unless you have an older Android OS, you typically want c for a refined animation.
  • 1 is the loop count. This means play once then proceed to the next sequence.
  • 15 is 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 15 is half of 30
  • part0 is the path to the collection of PNGs to use in this part
  • 000000 is 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)

  • c is still used, because this is where the OS will eventually finish loading. We want a graceful exit to the outro.
  • 0 is a special loop count. It means "loop forever". This part is where the OS will load and exit. Because we chose c it will gracefully exit to the end of the animation. If p was chosen, this is where the animation would abort & exit.
  • 0 means no delay. Duh.
  • part1 is the path to the collection of PNGs to use in this part
  • FF0000 means a red background for this part

Fourth Line (The Outro)

  • c is still used, because otherwise the outro would abort.
  • 1 is used because, thanks to c, the outro sequence must play even if the OS has loaded; so we play it once. If you chose p for the outro but c for prior parts, it'd exit immediately without playing. If you chose 0 here, the boot animation would loop forever and never stop!
  • 30 means pause a final second before showing the OS. Maybe your outro is fading to black so your final frame is a black screen.
  • part2 is the path to the collection of PNGs to use in this part
  • 0000FF means 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 desc.txt file.

Feel free to leave a comment if you have any questions and I'll try to answer them to the best of my ability.

This posts's header is by Kham Tran. Used under CC BY 2.0.