DEV Community: Song Yang

How to use Lottie animations in Flutter 3.16

Song Yang — Thu, 14 Mar 2024 00:04:13 +0000

In this tutorial, we go over the basics of Lottie animations and their use inside Flutter. We will see how Lottie animation files are represented in JSON and .lottie (DotLottie) formats. Then, we will put them into practice in a Flutter mobile app.

This is my system.

Software	Version	Notes
Flutter	3.16.9	Installed on Win 11 (not WSL)
Android SDK	34	Android Studio Hedgehog

Lottie Animations

Lottie animations are vector graphics animations. They are usually simple and short. Artists and designers can make the animations in Adobe After Effects or Figma, and then they can export them into a Lottie animation.

Here is an example animation on LottieFiles, a website for sharing Lottie animations.

The name "Lottie" is named after the film director Lotte Reineger.

File Formats

Lottie animations are not stored like normal animations, that is, in video files or GIFs. This is because the size of the files is too big and the pixelated resolution goes against responsive design.

In 2015, Hernan Torrisi developed a JSON format, now standardized by the Lottie Animation Community. The JSON format is minified for storage efficiency and rendered onto the screen by a player at runtime. Here is an introduction to the JSON format.

In 2020, LottieFiles developed a binary file format called .lottie (DotLottie), which is a ZIP version of the JSON format. The biggest benefit of .lottie is its much smaller file size, up to 70-90% smaller than JSON!

Using Lottie Animations

To use Lottie animations, we need a Lottie player that can parse the animation data from JSON or .lottie and render it to the screen. In Flutter, the most popular package for this is called lottie.

Setup

The animations we are using in this tutorial come from LottieFiles. Follow the links to download both the JSON and .lottie formats. In practice, we only need one format, but we will learn how to use both.

Create a Flutter project with flutter create. Move the downloaded files into an assets folder.

Modify the pubspec.yaml accordingly. Import the Lottie animation packages and expose the asset path.

# ...

dependencies:
    # ...

    # animations
    lottie: ^3.1.0
    dotlottie_loader: ^0.0.3 # only if you want to use .lottie

# ...

flutter:

    # ...

    # To add assets to your application, add an assets section, like this:
    assets:
        - assets/animations/

Importing JSON

To use the JSON format of a Lottie animation, it only takes one line.

For example, this is in main.dart.

import 'package:flutter/material.dart';
import 'package:lottie/lottie.dart';

void main() {
  runApp(const LottieExampleApp());
}

class LottieExampleApp extends StatelessWidget {
  const LottieExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Lottie.asset('assets/animations/Pyramid.json'), // <-- this line
      ),
    );
  }
}

Lottie.asset() is a named constructor available in lottie.

This will give you something like this. By default, the animation loops forever. To change that behavior, there are adjustable parameters in the Lottie.asset() method. For more fine-grained control, an AnimationController is needed.

Importing .lottie

Make sure the dotlottie_loader package has been added to the pubspec.yaml.

class LottieExampleApp extends StatelessWidget {
  const LottieExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: DotLottieLoader.fromAsset(
          "assets/animations/Pyramid.lottie",
          frameBuilder: (BuildContext context, DotLottie? dotlottie) {
            // check whether the animation has been loaded
            if (dotlottie != null) {
              return Lottie.memory(dotlottie.animations.values.single);
            } else {
              // what to render while it is loading
              return Container();
            }
          },
        ),
      ),
    );
  }
}

This produces the same thing as the JSON format but saves space on asset storage. Notice how the DotLottieLoader still needs the Lottie package. These two packages work together.

Animation Controllers

Animation controllers are widgets that control animations. We will use them to play the light switch animation from night to day and vice versa when the user taps on it.

To start, create a boilerplate animation controller widget using VS Code's Flutter extension. Simply type 'st' and select "Animation Controller". Alternatively, copy the following.

This is in a different Dart file called light_switch.dart.

class LightSwitch extends StatefulWidget {
  const LightSwitch({super.key});

  @override
  State<LightSwitch> createState() => _LightSwitchState();
}

class _LightSwitchState extends State<LightSwitch>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(vsync: this);
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return // widgets to show

Yes, animation controllers are just stateful widgets with a SingleTickerProviderStateMixin. With this, we don't have to use setState() at all!

Next, let's set up the .lottie import wrapped inside a GestureDetector.

@override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {}, // TODO!
      child: DotLottieLoader.fromAsset(
        'assets/animations/Light switch.lottie',
        frameBuilder: (context, dotLottie) {
          if (dotLottie != null) {
            return Lottie.memory(
              // .lottie can contain more than one animation
              // pick one
              dotLottie.animations.values.single,
              controller: _controller,
              onLoaded: (composition) {
                // the content of this Lottie animation
                _controller.duration = composition.duration;
              },
            );
          } else {
            // show nothing while it is loading
            return Container();
          }
        },
      ),
    );
  }

Here we add the duration of the animation to the controller during the onLoaded callback of the Lottie.memory() factory method. Without setting a duration, the animation cannot play.

Responding to User Taps

Let's write two methods that play the animation from night to day and vice versa.

We are still in the stateful widget's State<>.

  /// Animate the switch to the day position
  TickerFuture animateToDay() =>
      _controller.animateTo(_dayFrame / _composition.durationFrames); // a ratio

  /// Animate the switch to the night position
  TickerFuture animateToNight() => _controller.animateBack(0);

Let's define the private fields in the class.

  /// The frame on which the animation reaches the day state
  final double _dayFrame = 60;

  /// Information about the Lottie file
  late final LottieComposition _composition;

  // ... inside .lottie import
              onLoaded: (composition) {
                // the content of this Lottie animation
                _controller.duration = composition.duration;
                _composition = composition;
              },

The frame number 60 is found by watching the Lottie animation in a player. In frame 60, the animation reaches a state where it is day. Frame 0 starts with the night.

The two animation methods work by playing the animation

from frame 0 to 60: animateToDay()
from frame 60 to 0 in reverse: animateToNight()

The animation controller API takes in ratios when playing from frame number to frame number. As such, we give it the total frame count.

Tying Things Up

Finally, let's write the callback for the GestureDetector.

  /// Inner state for whether it is day or night
  bool _isDay = false;

  /// Change to day if night and vice versa.
  /// Ignore input if the animation is still in progress.
  void changeDayNight() async {
    if (_controller.isAnimating) return;
    if (_isDay == true) {
      await animateToNight();
      _isDay = false;
    } else {
      await animateToDay();
      _isDay = true;
    }
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: changeDayNight,
      // ...

TickerFuture is a Dart future. We wait for them to complete before switching the inner state Boolean so that the Boolean reflects the screen logic.

And voila!

If you need to check out the full source code, click here. Feel free to comment and file issues!

3 Ways to Package Your Java Project into a JAR for Deployment

Song Yang — Sun, 07 May 2023 16:51:42 +0000

In this tutorial, we will look at 3 ways to package your Java project into a JAR file, so you can ship your application to your users.

A JAR file is an archive that contains compiled Java source code and other things needed to run your program. With a functioning JAR, your user should only need a Java Runtime to run your code. They shouldn't need to compile your code by opening up an IDE or using a build tool. This makes it easy to deploy on different platforms. Hence, Java's slogan "Write once, run anywhere".

1. Building a single JAR

When your project is simple and you don't have many dependencies, building a JAR from your project is very easy. The jar task on Gradle is enough. Just make sure your build.gradle has your application's entry point (main class/main method) defined.

jar {
    // this is necessary to run your JAR
    manifest {
        attributes 'Main-Class': 'yourpackages.morepackages.YourMainClass'
    }

    // the rest is to access resource files like images, etc.
    duplicatesStrategy = DuplicatesStrategy.EXCLUDE

    from {
        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
    }
}

Then run this on the command line.

gradle jar

Your JAR file is produced inside the directory depending on your project IDE. For projects initialized with gradle only, that is build/libs/.

2. Building a JAR and delivering it with other JARs

It is possible that a fat JAR cannot be produced for reasons outside of your control. Fat JARs are supposed to contain everything you need to run the program, besides the Java Runtime. But sometimes, a certain dependency creates a problem with the building process. For example, building a Java project with JavaFX creates problems when attaching the JavaFX runtime to your JAR.

To remedy this, you can deliver several JARs at once and provide a script that launches the Java Runtime properly by referencing the third-party JARs.

A. Acquire the third-party JARs

For every third-party JARs you cannot integrate into your JAR, get the version of those JARs that you need. For example, download a version of the JavaFX runtime JAR to your computer.

B. Build your JAR alone

This step is similar to the situation where you build a single JAR.

C. Write a shell script (aka command-line script)

A shell script is a file that contains commands that you would run interactively on the command line. Instead of typing every command by hand one by one, you can write them into a file and run the file through the command line. The language of a shell depends on the system you intend to deploy your Java project. Here is a short list of commonly found shell languages.

Windows:
- Batch (.bat)
- Bash (.sh), if Git Bash is installed
Mac:
- Z Shell (.zsh)
- Bash (.sh), if the Mac is set up properly
Linux:
- Bash (.sh)

Begin your shell script with a shebang. This tells the command line what the file is. For example, the following shebang is for a Bash file. It must always be the first line of a shell script.

#!/bin/bash

Create a shell script. Usually, they are named run.sh or execute.sh. Inside it, you call the Java Runtime while referencing the third-party libraries' JARs and your JAR.

java --module-path path/to/your/third-party-JARs --add-modules module.you.need,second.module.you.need -jar your-project/build/libs/YourOwnJAR.jar

In this command, we call java by giving it a module path. The parameter path/to/your/third-party-JARs you supply here should be the location where you store your third-party JARs. Since we are deploying, we expect the JARs to be located in the same folder as the shell script. Therefore, we can use relative paths, e.g. javafx-sdk-20.0.1/lib. This assumes you moved the JavaFX folder next to your shell script.

Example file setup

your-current-working-directory/
|  YourOwnJAR.jar
|  javafx-sdk-20.0.1/
|  |  lib/
|  |  |  ... lots of JARs   
|  
|  run.sh

Example run.sh for a JavaFX project

#!/bin/bash
java --module-path javafx-sdk-20.0.1/lib --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media -jar YourOwnJar.jar

Don't forget to grant permission to the script with chmod.

chmod +x run.sh

To deliver this to your user, you would zip your-current-working-directory and send the archive. You would notify your user to unzip the archive and run the shell script by double-clicking it or through the command line with ./run.sh. This assumes your user has the appropriate shell language and Java Runtime.

3. Delivering a native application

This method is unlike the other two because it does not require the user to have anything installed, not even a Java Runtime! For situations where you want to deliver maximum application independence, this should be your go-to solution. For example, if you are dealing with people who have no idea what a shell script is or even what coding is, you should be sending everything as a self-contained double-clickable program.

The way this last method works is by shipping the Java Runtime with your JAR and dependencies. For those who don't know, the Java Runtime is an application designed to run compiled Java code on a specific operating system. As developers, we use the runtime that comes with the Java Development Kit (JDK). Two limitations of this method are the rather large deployment binary and the breaking of the slogan "Write once, run anywhere".

We will make use of the running example. This method builds upon Method 2.

A. Put all of your JARs (third-party or not) into a folder with your shell script

This step is the same as all of Method 2.

B. Download a copy of the Java Runtime Environment (JRE)

Next, you need to download a version of the Java Runtime. Head over to a distributor like the Eclipse Foundation and download a JRE that matches the version of your JDK. Although you can ship the JDK to your user, the file size would be very large (200+ MB) and it would contain many features that your user will never use. That's why we only need the JRE (40+ MB).

C. Move the JRE into your bundling folder

Assuming you have the same file structure from Method 2, you only need to move the unzipped JRE into your folder. The final file structure should look like this.

Example bundling folder structure

your-bundling-directory/
|  jre/ # <------------------------ moved here
|  YourOwnJAR.jar
|  javafx-sdk-20.0.1/
|  |  lib/
|  |  |  ... lots of JARs   
|  
|  run.sh

D. Edit the shell script

After being bundled (in later steps), the shell script cannot be directly run by the user clicking on it. As such, we need to make the script more independent.

One dependence that the script from Method 2 has is the assumption that the user has the java command installed on their machine. This time, we don't make this assumption and use the java from the Java Runtime copied to your-bundling-directory/jre/.

Shell scripts like Bash are also dependent on where the user calls them from. After being bundled, the user no longer calls the run.sh script directly. But it is still called by the bundling tool's runtime service when the user clicks on the executable. Therefore, we need to make sure the paths inside the script are all relative to the script's location.

In Bash, there is a special variable called BASH_SOURCE which contains the path to the directory where the Bash script is located. We will use this as a way to have relative paths.

Declare a variable in your run.sh called HERE. Pay attention to the spacing around the assignment operator =. It matters in Bash!

HERE=${BASH_SOURCE%/*}

In the above assignment, we make use of another Bash feature, string manipulation. This is done with the curly braces. In our case, we use the percent symbol % to truncate the / symbol and everything after inside the variable. * is the wild card operator from regular expressions. Since BASH_SOURCE contains a path to a directory, it ends with a slash on Linux and we don't want that.

Modify the java command of your run.sh.

"$HERE/jre/bin/java" --module-path "$HERE/javafx-sdk-20.0.1/lib" --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media -jar "$HERE/YourOwnJAR.jar" "$@"

Now, all the paths starts with the $HERE variable, which means it is all relative to the location of the run.sh script. In Bash, we reference variable using the $ symbol followed by the name of the variable. Notice here we put all the paths containing $HERE in double quotes. That is to take care of potential spaces inside path names, such as "Program Files".

You may also notice the last argument is "$@". This is also one of the default variables in Bash. $@ is a special variable that represents all the parameters the run.sh script has received through the command line. If your Java application takes command line arguments, this is absolutely necessary. Otherwise, it doesn't hurt to have it. This special variable is also enclosed in double quotes, because some arguments may contain white space themselves and that can cause argument splitting issues.

In summary, this is what a run.sh can look like for independent bundling.

#!/bin/bash

HERE=${BASH_SOURCE%/*}

"$HERE/jre/bin/java" --module-path "$HERE/javafx-sdk-20.0.1/lib" --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media -jar "$HERE/YourOwnJAR.jar" "$@"

Don't forget to test your shell script. Assuming you are outside the bundling directory, you can run the script through the command line.

./bundle/run.sh

E. Use `warp-packer` to produce a binary

Download the warp-packer tool to your system.

If you put the tool next to your bundling directory, then you can run the following commands.

./warp-packer --arch linux-x64 --input_dir your-bundling-directory --exec run.sh --output app.bin
chmod +x app.bin

In the first command,

--arch: the architecture you are deploying to. linux-x64 is the Linux operating system with x64 hardware.
--input_dir: the bundling directory you just prepared all this time
--exec: the executable shell script that runs when the binary is clicked
--output: the name of the produced binary with an extension of your choosing.

The second command grants permission to run the binary.

Test your binary.

./app.bin

In the JavaFX example, the binary size is about 108M for one of my students' projects. This is quite expected if you have resources like images in your Java project. Even after warp-packer compresses your files, most of the space is still taken by the Java Runtime Environment.

Competing tools for bundling Java

In a previous version of this article, I recommended jlink and jpackage for bundling Java into a native application. For simple applications, that can still work. However, these default tools in Java are no longer as reliable and as flexible as before. You can still find tutorials on them, but they only teach you how to bundle "Hello World"-level apps with little dependencies. This article dives deeper into software deployment with problematic Java dependencies such as JavaFX. As of the update of this article, I still couldn't get the default JDK tools to work with JavaFX.

Conclusion

In this blog, I explained 3 ways of deploying your Java project. Each method depends on your target user base. If they are okay with having some installed software on their machine. Delivering a JAR or a group of JARs + script is an acceptable solution. However, if you cannot expect your user to have any software installed, you should bundle everything into a standalone executable.