[web-animations-2] Progress APIs #8799

flackr · 2023-05-05T15:32:28Z

In #8669, #8765 and #8201 there seems to be a common desire to have more convenient APIs for getting some representation of progress. Currently you can get the progress of the current iteration of an effect using the getComputedTiming() API as follows:

let progress = animation.effect.getComputedTiming().progress;

You can also get the overall effect progress by doing a calculation such as:

let progress = animation.currentTime / animation.effect.getComputedTiming().endTime;

However, with several of the other linked issues it seems that it would be convenient for developers to have some form of access to the progress through the attached animation range, or to get that progress directly from the timeline.

We could add a convenience currentProgress helper alongside the currentTime API on Animation:

attribute double? currentProgress;

This could return the progress of currentTime through the entire range before which it is considered complete, e.g. calculated as follows:

currentProgress = currentTime / effect endTime

Note that endTime is infinite when either iterations or duration is infinite. In these cases currentProgress should probably be null or undefined?

Open question - should it be read only or should we allow setting the progress which would be equivalent to setting currentTime to currentProgress * endTime?

As per discussion on #8669 a progress reported on animation should be mostly independent of the effect timing, so we calculate it as the progress from startTime to the time when the animation would resolve its finished promise. This would intentionally not match the progress through the developer specified keyframes.

@birtles @bramus @fantasai

I also propose that given the uncertainty around what's expected from the getCurrentTime API on timeline, that we remove it until we have a better understanding of the specific use cases that developers need it for. Perhaps the animation progress API above will address some of them where it seems developers were trying to work this out through the timeline.

The text was updated successfully, but these errors were encountered:

birtles · 2023-05-06T01:22:39Z

Overall it seems reasonable to me. I think defining it in terms of startTime and endTime is a nice way of keeping it at arms length from effect timing.

Note that endTime is infinite when either iterations or duration is infinite. In these cases currentProgress should probably be null or undefined?

Mathematically, should it be zero? Not sure if that would be the most useful result, however.

Open question - should it be read only or should we allow setting the progress which would be equivalent to setting currentTime to currentProgress * endTime?

I'd suggest making it readonly. As you pointed out, there are some cases where this value would be null / undefined / 0 or somesuch, and in those cases if set made it writeable I guess the setter would throw?

We already have enough ways of changing the animation position (setting currentTime, setting startTime, calling the various playback methods etc.) and it's easy enough to make a read-only attribute writeable later if compelling use cases present themselves.

flackr · 2023-05-10T14:51:42Z

Mathematically, should it be zero? Not sure if that would be the most useful result, however.

Yeah, mathematically it would be 0. I don't have a strong preference for it to be null/undefined, just thought it might be marginally more meaningful than 0 to distinguish from the case of a 0 that can make progress.

bramus · 2023-05-12T17:32:17Z

In favor of this general approach as described here, to tackle #8669.

Fine with making it readonly as a starting point.

flackr · 2023-05-12T17:45:49Z

Thanks @bramus. Adding to agenda to discuss/resolve:

Add read-only currentProgress to Animation calculated as currentTime / effect endTime.
Should it return 0 (technically the mathematical result), null, or undefined when the animation end time is infinite?

ydaniv · 2023-05-13T13:19:24Z

Regarding 1. +1 on adding, with 2 suggestions:

Make it read/write. I think it should reflect the currentTime behavior and allow setting progress through this endpoint. It will both be, IMHO, more handy for authors, and if I'm not mistaken, should be necessary for animations with duration: auto.
How about naming it simply progress?

css-meeting-bot · 2023-05-24T16:46:42Z

The CSS Working Group just discussed [web-animations-2] Progress APIs, and agreed to the following:

RESOLVED: Add progress to Animation and make it readonly

The full IRC log of that discussion

<faceless> present-
<bramus> flackr: So WAAPI is very focused on absolute times, but with scroll-driven aninamations, developers often just work with progress instead of time
<bramus> flackr: seems like a reasonable thing to add, so there is a proposal to get the current progress which is a calcuation between start and and end time
<bramus> flackr: also need to specify what hsould happen for infinitely repeating animations
<bramus> flackr: Proposal is adding currentProgress to Animation
<bramus> flackr: it is calculated as currentTime / effect endTime
<bramus> flackr: propose to make it readonly for now
<bramus> s/repeating/duration/
<bramus> Rossen_: Any feedback?
<ydaniv> I proposed "progress" instead of "currentProgress"
<TabAtkins> +1
<TabAtkins> (to the current proposal, no opinion on naming)
<bramus> Rossen_: You are taking into account the feedback from ydaniv?
<bramus> flackr: Yes, he proposed currentProgress instead of progress
<bramus> flackr: dont object to this shorter name and computedTIming value from the effect is also called progress
<bramus> Rossen_: what about read/write vs readonly?
<bramus> flackr: then have to decide how to handle infinite duration animation
<bramus> Rossen_: starting with readonly gives up path to go forward later
<bramus> Rossen_: Should we formulate as readonly? not hearing objections from yehonathan
<bramus> flackr: would be happy with that
<bramus> bramus: me too
<bramus> Rossen_: objections to adding as readonly?
<bramus> Rossen_: Not hearing anything
<bramus> bramus: and the name?
<bramus> flackr: we said progress
<bramus> flackr: Proposed resolution: add progress to Animation and make it readonly
<bramus> RESOLVED: Add progress to Animation and make it readonly

flackr · 2024-02-29T16:13:31Z

On the PR from @DavMila there is one point where we don't have a clear answer. Should the progress be clamped to [0, 1]. For the full discussion you can view the PR review #9937 (comment) however I'll do my best to summarize the pros and cons of each.

Don't clamp the progress. This makes it similar to the currentTime which progress exists alongside (which also can be negative or greater than end time) and is the natural result of the expressed formula. This could be useful for example to distinguish between being at the start time (progress = 0) where the effect is active and visibly shown, and being before the start time (progress < 0) where the effect is not applied (unless fill = backwards | both). However, this also means that to correctly reflect the progress for 0 duration animations we would likely have to return -Infinity and Infinity when you are before or at/after the start time respectively.
Clamp the progress to [0, 1]. A developer won't be able to tell when at 0 progress whether the animation is active or not without also checking whether the currentTime is less than the start time. We could consider adding another member to animation to reflect this in the future.

Ultimately, I think either works, but which is better comes back to how authors will use this. @bramus @fantasai @birtles any thoughts?

ydaniv · 2024-02-29T20:08:07Z

I'm leaning towards 2, since this will probably be used to sync a scroll/view timeline with another effect that can't be done with CSS, e.g.: canvas, SVG, video.

So, I think that as default behavior, having this perform as a sort of "manual" CustomEffect, with a clamped progress like KeyframeEffect's is a good way to start, and we could add a new property in the future, like you said, to reflect the more complex cases.

birtles · 2024-02-29T22:44:11Z

I agree that 2 makes most sense. I also think, as per the current PR, we shouldn't try to reflect the fill mode of the associated effect.

ydaniv · 2024-03-01T15:34:02Z

However, if we consider the above use-cases, having enter/exit events on the animations, similar requested by @bramus on #7962 may become quite crucial for easily creating such effects without extra IntersectionObserver or scroll handler.
Although you can currently get a similar outcome with start/end events on CSS Animations like here: https://jsbin.com/jizahopixe/edit?css,js,console,output
I think it's currently not possible to achieve with WAAPI.

ydaniv · 2024-03-01T16:38:55Z

We could also resolve on adding start/end events on elements as per #9011 which should also help there

DavMila · 2024-09-17T17:52:51Z

I'll agenda+ this issue so we can get a formal resolution on the question on whether to clamp to [0,1].

ydaniv · 2024-09-19T19:39:58Z

Perhaps we should extract the idea of checking/specifying an effect in a before/after state?
Currently it requires hacks to achieve this, like setting delay: 1ms; play-state: paused for before.
For WAAPI you have to play and pause immediately.

ydaniv · 2024-09-22T18:08:35Z

If it helps, I can add an example from a research we started on doing exactly what I mentioned above:

I'm leaning towards 2, since this will probably be used to sync a scroll/view timeline with another effect that can't be done with CSS, e.g.: canvas, SVG, video.

Here: https://codepen.io/ydaniv/pen/VwNraKB - trying to scrub a <video>'s progress in-sync with a ScrollTimeline (spoiler: it doesn't work, at least OOTB). This is the kind of usages I think we'll mostly see for this API.

css-meeting-bot · 2024-09-26T22:37:37Z

The CSS Working Group just discussed [web-animations-2] Progress APIs, and agreed to the following:

RESOLVED: Clamp progress to [0,1]

The full IRC log of that discussion

<fserb> github-bot take up https://github.com//issues/8799
<fantasai> astearns: remaining question is whether we are clamping
<fantasai> flackr: we decided to add a progress accessor to animations
<fantasai> flackr: question was what to do outside the range of the animation
<fantasai> flackr: before animation starts or after it ends
<fantasai> flackr: I believe everyone is agreed that clamping is what makes sense, so want to resolve on it
<fantasai> flackr: [0%, 100%]
<fantasai> flackr: maps to the keyframe you're showing, assuming animation is in effect
<fantasai> astearns: any disagreement?
<fantasai> RESOLVED: Clamp progress to [0,1]

DavMila · 2024-10-29T16:38:04Z

Got some feedback that having AnimationEffect.getComputedTiming().progress and Animation.progress which mean different things could be confusing.
Could we consider renaming progress?
Perhaps totalProgress to reflect that it accounts for all the animation's iterations as opposed to AnimationEffect.getComputedTiming().progress which only accounts for the current iteration's progress.

flackr · 2024-10-29T17:06:46Z

Perhaps currentProgress would better align it with currentTime? I think we should also consider that if we want to later expose the effect phase (i.e. before/active/after), so if we went with currentProgress, currentPhase would make sense.

bramus · 2024-10-29T22:15:52Z

I like Rob’s suggestion

ydaniv · 2024-10-30T15:47:40Z

I don't know, IMHO, currentProgress looks awkward. And don't really think that those specifically meed to be consistent. I've seen usage of progress in libraries before. time by itself could be ambiguous, like start orend, but don't think progress is.

jyasskin · 2024-11-07T00:26:05Z

The concern isn't that progress itself is confusing, it's that myAnimation.effect.getComputedTiming().progress means one kind of progress, while myAnimation.progress means a different kind, and nothing in the names indicates the difference. I actually think it'd be ideal for getComputedTiming().progress to mention that it's the iteration's progress, but since that has been shipping for several years, I don't see much prospect for getting it renamed.

I'm not sure that currentProgress expresses the relevant difference here either (where totalProgress would), but the WG knows better than I do what context authors are likely to have when reading this code, and whether "current" is going to inspire the right intuition.

css-meeting-bot · 2024-11-07T00:50:23Z

The CSS Working Group just discussed [web-animations-2] Progress APIs, and agreed to the following:

RESOLVED: change Animation.progress to Animation.overallProgress

The full IRC log of that discussion

<TabAtkins> DavidA: we added a property field, it reflects the progress of the animation in a way that reflects the iterations of the animation
<TabAtkins> DavidA: there is a .progress that exists in AnimationEffect that has a .getComputedTiming() function
<TabAtkins> DavidA: but that only reflects the progress of the current animation
<TabAtkins> DavidA: got some feedback that it coudl be confusing to share the name since they mean different things
<TabAtkins> DavidA: wanted to consider renaming the Animation progress field either totalProgress or currentProgress
<TabAtkins> DavidA: not sure which is better to go with
<TabAtkins> DavidA: currentProgress is related to currentTime
<TabAtkins> DavidA: but totalProgress more strongly reflects taht it covers all the iterations
<TabAtkins> fantasai: okay so it's a .progress on AnimationEffect...
<TabAtkins> DavidA: no, on Animation itself
<TabAtkins> fantasai: is there one on AnimationEffect?
<TabAtkins> DavidA: indirectly, kinda
<DavidA> AnimationEffect.getComputedTiming().progress
<TabAtkins> vmpstr: yehonatan also said he thinks progress if fine and he'd find currentProgress confusing
<dholbert> https://www.w3.org/TR/web-animations-1/#calculating-the-overall-progress
<TabAtkins> dholbert: WebAnim 1 uses overallProgress
<TabAtkins> dholbert: it differentiates that from "simple" iteration progress
<fantasai> https://drafts.csswg.org/web-animations-1/#dictdef-computedeffecttiming
<TabAtkins> astearns: "overall" is just a name in the algo, not part of the exposed API?
<TabAtkins> dholbert: yeah
<fantasai> .endTie
<fantasai> .endTime
<fantasai> .activeDuration
<fantasai> .localTime
<fantasai> .progress
<TabAtkins> fantasai: so this is on an object called ComputedEffectTiming, which has...
<fantasai> .currentIteration
<TabAtkins> fantasai: and we're suggesting renaming .progress
<TabAtkins> fantasai: we currently have .activeDuration, .localTime, .currentIteration
<TabAtkins> DavidA: Oh, not the progress field on this object
<TabAtkins> DavidA: The one on the Animation class
<astearns> I kind of like `overallProgress`
<TabAtkins> yeah i'm kinda leaning toward overall
<fantasai> https://drafts.csswg.org/web-animations-1/#the-animation-interface
<TabAtkins> DavidA: .progress on ComputedEffectTiming has existed for a while, changing woudl be hard
<astearns> s/ComputedEffectTiming/getComputedTiming/
<TabAtkins> fantasai: can you string multiple Animations together?
<TabAtkins> DavidA: I'm not sure...
<TabAtkins> dholbert: i'm slightly uneasy about "total" because it sounds like a summation
<TabAtkins> +1
<fantasai> +1
<TabAtkins> astearns: I'd expect "total progress" to not change over time
<TabAtkins> DavidA: okay so overallProgress is still something we could consider, or currentProgress
<TabAtkins> fantasai: since timingeffect has currentTime and progress, what's the problem with just using progress on this?
<fantasai> s/currentTime/localTime/
<TabAtkins> fantasai: you'd get the context off of which object you're getting from
<astearns> request for something other than `progress`: https://github.com/w3ctag/design-reviews/issues/994#issuecomment-2427287323
<TabAtkins> astearns: [summarizes Jeffrey's comment]
<fantasai> TabAtkins: effect timing can run an animation multipel times, and progress gives you progress of the iteration
<fantasai> TabAtkins: this is a 0-1 and done thing, so it's a different concept than what the effect timing one is
<fantasai> TabAtkins: can't change that one, but maybe use a different word here
<TabAtkins> fantasai: i don't mind overall progress, i'm just saying we both have startTimes, they mean different things
<fantasai> fantasai: can tell from context
<fantasai> TabAtkins: progress has a different interpretation, because [missed]
<fantasai> TabAtkins: AnimationEffect has a .endTime
<fantasai> TabAtkins: Effect timing and animation have same interpretation of those
<dbaron> (last 2 lines were answering vmpstr asking about whether startTime has the same meaning on both)
<fantasai> TabAtkins: Animation has a .startTime and no .endTime / AnimationEffect has .endTime and no .startTime
<fantasai> vmpstr: Progress, one cycles per iteration, so wouldn't be the same value at any particular point
<fantasai> TabAtkins: for progress, right
<fantasai> vmpstr: but if startTime and endTime both existed on the same object, they would be the same, right?
<fantasai> TabAtkins: AFAICT from a quick read, they refer to the same type of concept
<fantasai> TabAtkins: it's beginning of whole thing it's doing, vs iteratin
<fantasai> astearns: gist I'm getting, is ppl think there's enough difference to have a different name
<TabAtkins> fantasai: i'm okay with overallProgress
<TabAtkins> astearns: so proposed resolution is we change Animation.progress to Animation.overallProgress
<TabAtkins> RESOLVED: change Animation.progress to Animation.overallProgress

In line with the CSS working group's resolution[1] to change Animation.progress to Animation.overallProgress, this patch updates the relevant portions of the web-animations-2 spec. [1] w3c#8799 (comment)

yisibl · 2024-11-13T06:37:30Z

Can we add these APIs to CSS?

ydaniv · 2024-11-13T08:51:52Z

Can we add these APIs to CSS?

Do you mean to the CSSAnimation interface? It inherits from Animation, so naturally yes.

In line with the CSS working group's resolution[1] to change Animation.progress to Animation.overallProgress, this patch updates the relevant portions of the web-animations-2 spec. [1] #8799 (comment) Co-authored-by: David Awogbemila <[email protected]>

graouts · 2024-11-25T10:51:14Z

I'm making the required WPT change also in web-platform-tests/wpt#49353.

In line with the CSS working group resolution in #8799[1], this patch renames Animation.progress in to Animation.overallProgress in Blink. [1] w3c/csswg-drafts#8799 (comment) Bug: 40914396 Change-Id: Ie7605f59d99314158b77e9672dbe98a564d2d1e6 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6049834 Commit-Queue: David Awogbemila <[email protected]> Reviewed-by: Robert Flack <[email protected]> Cr-Commit-Position: refs/heads/main@{#1387916}

In line with the CSS working group resolution in web-platform-tests#8799[1], this patch renames Animation.progress in to Animation.overallProgress in Blink. [1] w3c/csswg-drafts#8799 (comment) Bug: 40914396 Change-Id: Ie7605f59d99314158b77e9672dbe98a564d2d1e6 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6049834 Commit-Queue: David Awogbemila <[email protected]> Reviewed-by: Robert Flack <[email protected]> Cr-Commit-Position: refs/heads/main@{#1387916}

In line with the CSS working group resolution in #8799[1], this patch renames Animation.progress in to Animation.overallProgress in Blink. [1] w3c/csswg-drafts#8799 (comment) Bug: 40914396 Change-Id: Ie7605f59d99314158b77e9672dbe98a564d2d1e6 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6049834 Commit-Queue: David Awogbemila <[email protected]> Reviewed-by: Robert Flack <[email protected]> Cr-Commit-Position: refs/heads/main@{#1387916}

…verallProgress, a=testonly Automatic update from web-platform-tests Rename Animation.progress to Animation.overallProgress In line with the CSS working group resolution in #8799[1], this patch renames Animation.progress in to Animation.overallProgress in Blink. [1] w3c/csswg-drafts#8799 (comment) Bug: 40914396 Change-Id: Ie7605f59d99314158b77e9672dbe98a564d2d1e6 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6049834 Commit-Queue: David Awogbemila <[email protected]> Reviewed-by: Robert Flack <[email protected]> Cr-Commit-Position: refs/heads/main@{#1387916} -- wpt-commits: 9c416ba6fc2a085fde55600a0056ac30304a8f1f wpt-pr: 49385

flackr added the web-animations-2 Current Work label May 5, 2023

flackr mentioned this issue May 12, 2023

[scroll-animations-1] currentTime for animations attached to a timeline attachment range #8669

Closed

flackr added the Agenda+ label May 12, 2023

css-meeting-bot removed the Agenda+ label May 24, 2023

mozilla-apprentice mentioned this issue May 24, 2023

[web-animations-2] Progress APIs mozilla/wg-decisions#1132

Closed

chromium-helper mentioned this issue May 24, 2023

[web-animations-2] Progress APIs chromium-helper/csswg-resolutions#127

Closed

fantasai added Closed Accepted by CSSWG Resolution Needs Edits labels Jun 1, 2023

fantasai mentioned this issue Jun 1, 2023

[scroll-animations-1][web-animations-2] getCurrentTime is self-inconsistent wrt representing time #8765

Open

bramus mentioned this issue Jul 25, 2023

[web-animations-2] [css-animations-2] Allow animations to be synchronized to the playback of audio or video elements #9110

Open

DavMila mentioned this issue Feb 12, 2024

[web-animations-2] Specify Animation progress API #9937

Merged

DavMila mentioned this issue Sep 17, 2024

Spec review for Animation.progress w3ctag/design-reviews#994

Closed

1 task

DavMila added the Agenda+ TPAC label Sep 17, 2024

astearns added this to CSSWG Agenda TPAC 2024 Sep 17, 2024

astearns moved this to TPAC/FTF agenda items in CSSWG Agenda TPAC 2024 Sep 17, 2024

css-meeting-bot removed the Agenda+ TPAC label Sep 26, 2024

mozilla-apprentice mentioned this issue Sep 26, 2024

[web-animations-2] Progress APIs mozilla/wg-decisions#1636

Closed

DavMila added the Agenda+ label Oct 30, 2024

css-meeting-bot removed the Agenda+ label Nov 7, 2024

mozilla-apprentice mentioned this issue Nov 7, 2024

[web-animations-2] Progress APIs mozilla/wg-decisions#1691

Closed

DavMila mentioned this issue Nov 12, 2024

[web-animations-2] Change progress to overallProgress #11184

Merged

This was referenced Nov 20, 2024

Animation.progress mozilla/standards-positions#1073

Open

Animation.progress WebKit/standards-positions#398

Open

dev-ansung mentioned this issue Nov 27, 2024

Rename Animation.progress to Animation.overallProgress web-platform-tests/wpt#49385

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[web-animations-2] Progress APIs #8799

[web-animations-2] Progress APIs #8799

flackr commented May 5, 2023

birtles commented May 6, 2023

flackr commented May 10, 2023

bramus commented May 12, 2023

flackr commented May 12, 2023

ydaniv commented May 13, 2023

css-meeting-bot commented May 24, 2023

flackr commented Feb 29, 2024

ydaniv commented Feb 29, 2024

birtles commented Feb 29, 2024

ydaniv commented Mar 1, 2024

ydaniv commented Mar 1, 2024

DavMila commented Sep 17, 2024

ydaniv commented Sep 19, 2024

ydaniv commented Sep 22, 2024

css-meeting-bot commented Sep 26, 2024

DavMila commented Oct 29, 2024

flackr commented Oct 29, 2024

bramus commented Oct 29, 2024

ydaniv commented Oct 30, 2024

jyasskin commented Nov 7, 2024

css-meeting-bot commented Nov 7, 2024

yisibl commented Nov 13, 2024

ydaniv commented Nov 13, 2024

graouts commented Nov 25, 2024

[web-animations-2] Progress APIs #8799

[web-animations-2] Progress APIs #8799

Comments

flackr commented May 5, 2023

birtles commented May 6, 2023

flackr commented May 10, 2023

bramus commented May 12, 2023

flackr commented May 12, 2023

ydaniv commented May 13, 2023

css-meeting-bot commented May 24, 2023

flackr commented Feb 29, 2024

ydaniv commented Feb 29, 2024

birtles commented Feb 29, 2024

ydaniv commented Mar 1, 2024

ydaniv commented Mar 1, 2024

DavMila commented Sep 17, 2024

ydaniv commented Sep 19, 2024

ydaniv commented Sep 22, 2024

css-meeting-bot commented Sep 26, 2024

DavMila commented Oct 29, 2024

flackr commented Oct 29, 2024

bramus commented Oct 29, 2024

ydaniv commented Oct 30, 2024

jyasskin commented Nov 7, 2024

css-meeting-bot commented Nov 7, 2024

yisibl commented Nov 13, 2024

ydaniv commented Nov 13, 2024

graouts commented Nov 25, 2024