feat: Lottie animation renders at composition frame rate, reducing unnecessary load

[OuHT]

From issue #419

Lottie animation renders at composition frame rate, reducing unnecessary load

Flutter Ticker forces Lottie animation to synchronize with 60Hz Vsync. Even when the composition's original frame rate (fr field) is only 15/30fps, the system still executes the full rendering pipeline at 60Hz, causing unnecessary CPU/GPU load.

This solution adopts Timer drive by default, rendering at the composition's original frame rate or configured frameRate, decoupling animation frequency from screen refresh rate to reduce power consumption.

Key Changes

Change	Description
Default Timer drive	Without external controller / with LottieController, render via Timer at configured frame rate
Compatible Ticker drive	With external AnimationController, automatically uses original Ticker drive
New LottieController	Same API as AnimationController, no TickerProviderStateMixin required
frameRate takes effect	Configuring FrameRate(30) or FrameRate.composition renders at specified frame rate

Usage

// Default: Timer drive at composition's original frame rate (fr field)
Lottie.asset('assets/animation.json')

// Specify 30fps
Lottie.asset('assets/animation.json', frameRate: FrameRate(30))

// External LottieController
late final LottieController _controller;

Measured Benefits (Android)

Test Demo:

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

void main() => runApp(const MyApp());

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: ListView(
          children: [
            // Load a Lottie file from your assets
            Lottie.asset('assets/LottieLogo1.json'),
          ],
        ),
      ),
    );
  }
}

Rendering at fr-specified frame rate from JSON:

Metric	Before (Ticker 60Hz)	After (Timer at fr-specified rate)	Reduction
Test 1	4,768,733,827	2,783,022,888	41.6%
Test 2	4,591,814,457	2,975,770,379	35.2%
Test 3	4,765,358,968	2,938,497,704	38.3%
Average	4,708,635,751	2,899,097,124	38.4%

Average 38.4% reduction in rendering overhead.

Backward Compatibility

Existing AnimationController code works without modification, automatically uses Ticker drive.

[xvrh]

@OuHT Did you try the frameRate property: https://github.com/xvrh/lottie-flutter#frame-rate
What is better here?

[OuHT]

@xvrh Yes, I have tried the frameRate property. However, compared to our current driver solution, the power savings were not significant.

[xvrh]

Can you explain me what the trick is then? The existing frameRate tries to not schedule a repaint when it's not necessary. Is it the build itself that is eating the CPU?

[OuHT]

The existing frameRate tries to not schedule a repaint when it's not necessary. It only skips the repaint, but doesn't skip the entire VSync wake-up mechanism that causes the repaint.

It's not the build itself, but being forced to run build 60 times/second that eats the CPU (assuming a 60Hz screen):

frameRate=30: VSync wakes up every 16.7ms → build runs 60/s, paint is just skipped at the end
Timer 30Hz: No VSync forced wake-up → build only runs 30/s

Can you explain me what the trick is then? The existing frameRate tries to not schedule a repaint when it's not necessary. Is it the build itself that is eating the CPU?

[OuHT]

Summary

frameRate only skips paint, but VSync still wakes up the entire Flutter pipeline every 16.7ms. Timer skips VSync itself.

---

The problem with existing frameRate: VSync loop can't stop

VSync interrupt (16.7ms)
  ↓
AnimationController.tick → notifyListeners()
  ↓
AnimatedBuilder.build() → setProgress() → roundProgress()
  ↓
markNeedsPaint()? ❌ skipped (the only one skipped)
paint()? ❌ skipped (the only one skipped)
  ↓
Engine::RequestFrame() → register next VSync
  ↓
Back to start, wake up again after 16.7ms...

Even with frameRate=30, this loop still runs every 16.7ms. roundProgress() finds the frame hasn't changed, only skips paint, but all preceding steps like build still execute.

Why can't RequestFrame() stop? AnimationController registers callbacks with SchedulerBinding through Ticker:

Ticker.scheduleTick() →
SchedulerBinding.scheduleFrameCallback() →
scheduleFrame() →
platformDispatcher.scheduleFrame().

The Engine calls scheduleFrame() at the end of every frame to register the next VSync, forming an infinite loop. As long as AnimationController is running, this loop cannot stop.

---

Timer drive: Breaking the VSync loop

Timer (33ms)
  ↓
setState() → build() → setProgress()
  ↓
markNeedsPaint() → paint() → GPU
  ↓
Trigger again after 33ms...

No AnimationController, no Ticker, no RequestFrame(). The VSync loop is broken.

Why doesn't Timer trigger RequestFrame()? setState() only marks the current Element as dirty, adding it to BuildOwner's dirty list. It does not call scheduleFrame(), does not request VSync from the Engine. Only when VSync arrives due to other reasons (like user interaction or other animations) will it rebuild in handleBuildDirtyElements(). Timer controls its own trigger rhythm at 33ms intervals, independent of VSync.

---

[OuHT]

Use the above Test Demo

[OuHT]

Hi @xvrh , sorry for the follow-up.

Regarding the implementation details I explained earlier, I was wondering if the explanation was clear enough, or if there's anything I should clarify?

I'd be happy to add more test cases or adjust the implementation approach if needed. Looking forward to your feedback. Thank you!

[xvrh]

@OuHT I propose this alternative approach that should bring the same gains: #423

[OuHT]

@xvrh I studied your PR, the gate rebuild approach is clever and does reduce unnecessary build calls.

I tested three approaches with a 30fps composition on a 60Hz screen, measuring CPU cycles:

Approach	Test 1	Test 2	Test 3	Average	vs Baseline
Baseline	4,777M	4,767M	4,749M	4,764M	baseline
Your PR (gate rebuild)	4,463M	4,759M	4,739M	4,654M	-2.3%
Timer drive	2,901M	2,943M	2,962M	2,935M	-38.4%

Your PR successfully reduced Lottie widget's rebuild frequency (from 60/s to ~28/s), but the AnimationController VSync loop still runs at 60Hz:

VSync (16.7ms) → AnimationController.tick → notifyListeners → [gate: skip Lottie build] → RequestFrame → next VSync

The gate skips Lottie's build()/paint(), but all upstream steps (VSync interrupt, Engine scheduling, ticker callback, listener notification) still fire 60 times per second — this overhead is the dominant cost.

Timer drive bypasses AnimationController and breaks this VSync loop entirely:

Timer (33ms) → setState() → build → paint

No AnimationController, no Ticker, no RequestFrame(). The whole pipeline truly drops to 30Hz.

To achieve this, I added LottieController as an alternative. It fully replaces AnimationController as an external controller, with the same control API (forward/reverse/stop/repeat/animateTo), same listener interface (addListener/addStatusListener), same property access (value/status/isAnimating). In my follow-up commits, it now also supports TickerMode (via setTickerModeEnabled()) and App Lifecycle (internal AppLifecycleListener for auto pause/resume).

External Controller Comparison:

External Controller	Drive Mode	TickerMode	App Lifecycle
LottieController	Timer	✅	✅
AnimationController	Ticker	✅	✅

Both controllers support TickerMode and App Lifecycle, just with different drive mechanisms.

Perfetto confirms this — your PR keeps AsyncWorker wake-up interval at 16.7ms, while Timer drive changes it to 33.3ms.

Would you consider defaulting to Timer drive when no external controller is provided, using Timer drive with LottieController, and automatically falling back to Ticker drive with AnimationController for compatibility? This achieves 38% power savings while fully maintaining backward compatibility.

[xvrh]

@OuHT can you have a look at this alternative PR #426 and test it with your benchmark. Thanks