Timeline orchestration

Most of the time, .animate() on each element is all you need. When you want to place many animations on one shared clock, reach for Timeline. It is an opt-in, GSAP-style builder that records steps against a running playhead:

Timeline introTimeline(Anchor title, Anchor subtitle, List<Anchor> bullets, Anchor cta) =>
    Timeline(defaults: const Defaults(duration: Time.seconds(0.5)))
      ..play(title, Animation.slideFadeIn())
      ..play(subtitle, Animation.fadeIn(), at: Trigger.whenEnds(title))
      ..wait(0.3.seconds)
      ..playAll(bullets, Animation.slideFadeIn(), stagger: 0.08.seconds)
      ..label('reveal')
      ..play(cta, Animation.pop(), at: 'reveal'.label - 0.2.seconds);

Timeline is experimental. Its surface may change before 1.0.

How the playhead moves

Each call advances a playhead, the running position the next step starts from:

• play(target, animation) places one animation and moves the playhead to its end.
• playAll(targets, animation, stagger:) places one animation on many targets, staggered, and moves the playhead to the last one’s end.
• wait(time) advances the playhead with no step.
• label(name) records the playhead under a name.

duration is the end of the latest step, derived for you.

Placing a step with at:

at: overrides where a step starts. It accepts three things:

• a Trigger, for example Trigger.whenEnds(title) to start when title ends;
• a String label, for example at: 'reveal';
• a LabelRef with offset arithmetic, for example 'reveal'.label - 0.2.seconds.

Label arithmetic stays symbolic until the timeline resolves its placements at the enclosing Video’s fps, so it never reaches the per-frame path. An unknown label already throws at the play() call.

Driving a scene

Hand a Timeline to Scene.sequence and the scene adopts the timeline’s derived length. You declare the structure once and the scene runs on it:

Scene sequencedScene(Timeline timeline) => Scene.sequence(
  timeline: timeline,
  background: Background.color(const Color(0xFF101820)),
  children: const [Text('Built on one clock')],
);

The timeline has no clock of its own: every Time in it resolves at the enclosing Video’s fps, so the same timeline places identically at 30 or 60 fps.

Where to next

• Timing and triggers: the triggers and anchors the timeline resolves against.
• Cheatsheet: the whole shipped surface on one page.