commit	156a0ce18b75eacf87b361d00831c0ff60e44e2b	[log] [tgz]
author	Gabriel Peal <gabriel.peal@airbnb.com>	Tue Jan 03 16:43:02 2017 -0800
committer	Gabriel Peal <gabriel.peal@airbnb.com>	Tue Jan 03 16:43:02 2017 -0800
tree	c8adfc003994c7e5447ddc51bea9b1667ebabfc1
parent	15b817f077c6f6cd07fd335331adba1e62db5dd5 [diff]

tree: c8adfc003994c7e5447ddc51bea9b1667ebabfc1

README.md

Lottie for Android (and iOS)

Lottie is a mobile library for Andorid and iOS that parses Adobe After Effects animations exported as json with bodymovin and renders them natively on mobile!

For the first time, designers can create and ship beautiful animations without an enginineer painstakingly recreating it be hand.

They say a picture is worth 1,000 words so here are 7,000

Lightbulb Business

AllSet Selfie

Abcs

Download

Gradle is the only supported build configuration, so just add the dependency to your project build.gradle file:

dependencies {
  compile 'com.airbnb.android:lottie-android:1.0.0'
}

Using Lottie

Lottie supports Jellybean (API 16) and above. The simplest way to use it is with LottieAnimationView:

<com.airbnb.lottie.LottieAnimationView
        android:id="@+id/animation_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        app:lottie_fileName="hello-world.json"
        app:lottie_loop="true"/>

Or you can load it programatically:

LottieAnimationView animationView = findViewById(R.id.animation_view);
animationView.setAnimation("hello-world.json");
animationView.loop(true);
animationView.playAnimation();

You can also load the composition directly using LottieComposition and pass it to a LottieAnimationView or LottieDrawable.

In addition, LottieViewAnimator allows you to define a view animation with After Effects. Check the docs for LottieViewAnimator to learn more.

Performance

If the composition has no masks or mattes then the performance and memory overhead should be quite good. No bitmaps are created and most operations are simple canvas draw operations.
If the composition has mattes, 2-3 bitmaps will be created at the composition size. The bitmaps are created automatically by lottie when the animation view is added to the window and recycled when it is removed from the window. For this reason, it is not recommended to use animations with masks or mattes in a RecyclerView because it will cause significant bitmap churn.
In addition to memory churn, additional bitmap.eraseColor() and canvas.drawBitmap() calls are necessary which will slow down the performance of the animation. For small animations, the performance hit shouldn't be large enough to be obvious when actually used.
If you are using your animation in a list, it is recommended to use a CacheStrategy in LottieAnimationView.setAnimation(String, CacheStrategy) so the animations doesn't have to be deserialized every time.

Try it out

Clone this repository and run the LottieSample module to see a bunch of sample animations. The JSON files for them are located in /assets.

The sample app can also load json files at a given url or locally on your device (like Downloads or on your sdcard).

Alternatives

Build animations by hand. Building animations by hand is a huge time commitment for design and engingeering across Android and iOS. It's often hard or even impossible to justify spending so much time to get an animation right.
Facebook Keyframes. Keyframes is a wonderful new library from Facebook that they built for reactions. However, it only supports a small subset of the features suppoted by Lottie such as masks, mattes, trim paths, dash patterns, and more.
Gifs. Gifs are more than double the size of a bodymovin JSON and are rendered at a fixed size that can't be scaled up to match large and high density screens.
Png sequences. Png sequences are even worse than gifs in that their file sizes are often 30-50x the size of the bodymovin json and also can't be scaled up.

Why is it called Lottie?

Lottie is named after a German film director and the foremost pioneer of silhouette animation. Her best known films are The Adventures of Prince Achmed (1926) – the oldest surviving feature-length animated film, preceding Walt Disney's feature-length Snow White and the Seven Dwarfs (1937) by over ten years The art of Lotte Reineger

Contributing

Contributers are more than welcome. Just upload a PR with a description of your changes. Lottie uses Facebook screenshot tests for Android to identify pixel level changes/breakages. Please run ./gradlew --daemon recordMode screenshotTests before uploading a PR to ensure that nothing has broken. Changed screenshots will show up in your git diff if you have.

If you would like to add more JSON files and screenshot tests, feel free to do so and add the test to LottieTest.

Issues?

File github issues for anything that is unexpectedly broken. If an After Effects file is not working, please attach it to your issue. Debugging without the original file is much more difficult.