Web Animations

1. Introduction

2. Web Animations model overview

This section is non-normative

At a glance, the Web Animations model consists of two largely independent pieces, a timing model and an animation model. The role of these pieces is as follows:

Timing model

Takes a moment in time and converts it to a proportional distance within a single iteration of an animation called the iteration progress. The iteration index is also recorded since some animations vary each time they repeat.

Animation model

Takes the iteration progress values and iteration indices produced by the timing model and converts them into a series of values to apply to the target properties and attributes.

Graphically, this flow can be represented as follows:

Overview of the operation of the Web Animations model.
The current time is input to the timing model which produces an iteration progress value and an iteration index.
These parameters are used as input to the animation model which produces the values to apply.

For example, consider an animation that:

• starts after 3 seconds

• runs twice,

• takes 2 seconds every time, and

• changes the width of a rectangle from 50 pixels to 100 pixels.

The first three points apply to the timing model. At a time of 6 seconds, it will calculate that the animation should be half-way through its second iteration and produces the result 0.5. The animation model then uses that information to calculate a width.

This specification begins with the timing model and then proceeds to the animation model.

3. Timing model

This section describes and defines the behavior of the Web Animations timing model.

3.1. The timing model at a glance

3.2. Timing model concepts

In Web Animations, timing is based on a hierarchy of time relationships between timing nodes. Parent nodes provide timing information to their child nodes in the form of time values. A time value is a real number which nominally represents a number of milliseconds from some moment. The connection between time values and wall-clock milliseconds may be obscured by any number of transformations applied to the value as it passes through the time hierarchy.

In the future we may have timelines that are based on UI gestures in which case the connection between time values and milliseconds will be weakened even further.

A time value may also be unresolved if, for example, a timing node is not in a state to produce a time value.

Periodically, the user agent will update the timing model in a process called sampling. On each sample the time values of each timing node are updated.

Further requirements on the frequency and sequencing of sampling are specified by HTML’s processing model [HTML].

Note: HTML currently refers to a “run CSS animations and send events” operation but this should be understood to include sampling all animations covered by this specification, not only CSS animations. Furthermore, the now parameter passed to this operation is ignored in this specification since we define a more general model that supports timelines whose time origin is not relative to navigationStart.

3.3. The global clock

At the root of the Web Animations timing hierarchy is the global clock.

The global clock is a source of monotonically increasing time values unaffected by adjustments to the system clock. The time values produced by the global clock represent wall-clock milliseconds from an unspecified historical moment. Because the zero time of the global clock is not specified, the absolute values of the time values produced by the global clock are not significant, only their rate of change.

Note: The global clock is not exposed in the programming interface and nor is it expected to be exposed by markup. As a result the moment from which global clock time values are measured, that is, the zero time of the clock, is implementation-dependent. One user agent may measure the number of milliseconds since the the user agent was loaded whilst another may use the time when the device was started. Both approaches are acceptable and produce no observable difference in the output of the model.

3.4. Timelines

A timeline provides a source of time values for the purpose of synchronization.

Typically, a timeline is tied to the global clock such that its absolute time is calculated as a fixed offset from the time of the global clock. This offset is established by designating some moment as the timeline’s zero time and recording the time value of the global clock at that moment. At subsequent moments, the time value of the timeline is calculated as the difference between the current time value of the global clock and the value recorded at the zero time.

On each sample, the time value of the global clock at the beginning of the sample is recorded and this recorded value is used as the time value of the global clock until the next sample.

Note: We anticipate that other types of timelines may be introduced in the future that are not tied to the global clock. For example, a timeline whose time values are related to the progress of a UI gesture.

Since a timeline may be defined relative to a moment that has yet to occur, it may not always be able to return a meaningful time value, but only an unresolved time value. A timeline is considered to be inactive when its time value is unresolved.

3.4.1. Document timelines

A document timeline is a timeline that is associated with a document.

The time values of a document timeline are calculated as a fixed offset from the global clock such that the zero time corresponds to the navigationStart moment [NAVIGATION-TIMING] plus a signed delta known as the origin time. Prior to establishing the navigationStart moment, the document timeline is inactive.

A document timeline that is associated with a document which is not an active document is also considered to be inactive.

3.4.2. The default document timeline

Each document ([DOM]) has a document timeline called the default document timeline. The default document timeline is unique to each document and persists for the lifetime of the document including calls to document.open() [HTML5].

The default document timeline has an origin time of zero.

3.5. Animations

An animation connects a single animation effect, called its target effect, to a timeline and provides playback control. Both of these associations are optional and configurable such that an animation may have no associated target effect or timeline at a given moment.

An animation’s start time is the time value of its timeline when its target effect is scheduled to begin playback. An animation’s start time is initially unresolved.

An animation also maintains a hold time time value which is used to fix the animation’s output time value, called its current time, in circumstances such as pausing. The hold time is initially unresolved.

In order to establish the priority of conflicting animations, each animation has an associated animation sequence number that is assigned a globally unique sequence number each time it transitions out of the idle play state.

3.5.1. Setting the timeline of a animation

The procedure to set the timeline of an animation, animation, to new timeline which may be null, is as follows:

1. Let old timeline be the current timeline of animation, if any.

2. If new timeline is the same object as old timeline, abort this procedure.

3. Let previous animation time be the current time of animation.

4. If new timeline is null and old timeline is not null, run the procedure to reset an animation’s pending tasks on animation.

   Note that if new timeline is not null and animation has a pending play task or a pending pause task no special handling is required: the pending task will run as soon as the animation is ready even though this may occur at a different moment than it might have done with the old timeline.

5. Let the timeline of animation be new timeline.

6. If previous animation time is resolved, run the procedure to silently set the current time of animation to previous animation time.

7. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false.

The procedure to reset an animation’s pending tasks for animation is as follows:

1. If animation has a pending play task, cancel that task.

2. If animation has a pending pause task, cancel that task.

3. Reject animation’s current ready promise with a DOMException named "AbortError".

4. Let animation’s current ready promise be the result of creating a new resolved Promise object.

3.5.2. Setting the target effect of an animation

The procedure to set the target effect of an animation, animation, to new effect which may be null, is as follows:

1. Let old effect be the current target effect of animation, if any.

2. If new effect is the same object as old effect, abort this procedure.

3. If new effect is null and old effect is not null, run the procedure to reset an animation’s pending tasks on animation.

4. If animation has a pending pause task, reschedule that task to run as soon as animation is ready.

5. If animation has a pending play task, reschedule that task to run as soon as animation is ready to play new effect.

6. If new effect is not null and if new effect is the target effect of another animation, previous animation, run the procedure to set the target effect of an animation (this procedure) on previous animation passing null as new effect.

7. Let the target effect of animation be new effect.

8. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false.

3.5.3. The current time of an animation

Animations provide a time value to their target effect called the animation’s current time.

The current time is calculated from the first matching condition from below:

3.5.4. Setting the current time of an animation

The current time of an animation can be set to a new value to seek the animation. The procedure for setting the current time is split into two parts.

The procedure to silently set the current time of an animation, animation, to seek time is as follows:

1. If seek time is an unresolved time value, then perform the following steps.

   1. If the current time is resolved, then throw a TypeError.

   2. Abort these steps.

2. Update either animation’s hold time or start time as follows:

   If any of the following conditions are true:

   • animation’s hold time is resolved, or

   • animation’s start time is unresolved, or

   • animation has no associated timeline or the associated timeline is inactive, or

   • animation’s playback rate is 0,

   Set animation’s hold time to seek time.

   Otherwise,

   Set animation’s start time to the result of evaluating timeline time - (seek time / playback rate) where timeline time is the current time value of timeline associated with animation.

3. If animation has no associated timeline or the associated timeline is inactive, make animation’s start time unresolved.

   This preserves the invariant that when we don’t have an active timeline it is only possible to set either the animation start time or the animation’s current time.

4. Make animation’s previous current time unresolved.

The procedure to set the current time of an animation, animation, to seek time is as follows:

1. Run the steps to silently set the current time of animation to seek time.

2. If animation has a pending pause task, synchronously complete the pause operation by performing the following steps:

   1. Set animation’s hold time to seek time.

   2. Make animation’s start time unresolved.

   3. Cancel the pending pause task.

   4. Resolve animation’s current ready promise with animation.

3. Run the procedure to update an animation’s finished state for animation with the did seek flag set to true.

3.5.5. Setting the start time of an animation

The procedure to set the animation start time of animation, animation, to start time, new start time, is as follows:

1. Let timeline time be the current time value of the timeline that animation is associated with. If there is no timeline associated with animation or the associated timeline is inactive, let the timeline time be unresolved.

2. If timeline time is unresolved and new start time is resolved, make animation’s hold time unresolved.

   This preserves the invariant that when we don’t have an active timeline it is only possible to set either the animation start time or the animation’s current time.

3. Let previous current time be animation’s current time.

   Note: This is the current time after applying the changes from the previous step which may cause the current time to become unresolved.

4. Set animation’s start time to new start time.

5. Update animation’s hold time based on the first matching condition from the following,

   If new start time is resolved,

   If animation’s playback rate is not zero, make animation’s hold time unresolved.

   Otherwise (new start time is unresolved),

   Set animation’s hold time to previous current time even if previous current time is unresolved.

6. If animation has a pending play task or a pending pause task, cancel that task and resolve animation’s current ready promise with animation.

7. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false.

Is this right? If you shift an animation backwards in time so that it is now finished, should the current time jump to the end of the target effect, or be allowed to sit past the end of the target effect?

3.5.6. Waiting for the target effect

An animation is ready at the first moment where both of the following conditions are true:

• the user agent has completed any setup required to begin the playback of the animation’s target effect including rendering the first frame of any keyframe effect.

• the animation is associated with a timeline that is not inactive.

3.5.7. Promise objects

Promise objects are defined by [ECMA-262], section 25.4.

To resolve a Promise with value, call the [[Call]] internal method of [[Resolve]] on the Promise capability record for the promise, passing undefined as thisArgument and (value) as argumentsList.

To reject a Promise with reason, call the [[Call]] internal method of [[Reject]] on the Promise capability record for the promise, passing undefined as thisArgument and (reason) as argumentsList.

To create a new resolved Promise with value, call Promise.resolve, passing value as x.

3.5.8. The current ready promise

Each animation has a current ready promise. The current ready promise is initially a resolved Promise created using the procedure to create a new resolved Promise.

The object is replaced with a new Promise object every time the animation enters the pending play state as well as when the animation is cancelled (see §3.5.15 Cancelling an animation).

animation.pause();
animation.ready.then(function() {
  // Displays 'running'
  alert(animation.playState);
});
animation.play();

3.5.9. Playing an animation

The procedure to play an animation, animation, is as follows:

1. Let aborted pause be a boolean flag that is true if animation has a pending pause task, and false otherwise.

2. Let has pending ready promise be a boolean flag that is initially false.

3. Perform the steps corresponding to the first matching condition from the following, if any:

   If animation playback rate > 0 and either animation’s:

   • current time is unresolved, or

   • current time < zero, or

   • current time ≥ target effect end,

   Set animation’s hold time to zero.

   If animation playback rate < 0 and either animation’s:

   • current time is unresolved, or

   • current time ≤ zero, or

   • current time > target effect end,

   If target effect end is positive infinity, throw an InvalidStateError and abort these steps. Otherwise, set animation’s hold time to target effect end.

   If animation playback rate = 0 and animation’s current time is unresolved,

   Set animation’s hold time to zero.

4. If animation has a pending play task or a pending pause task,

   1. Cancel that task.

   2. Set has pending ready promise to true.

5. If animation’s hold time is unresolved and aborted pause is false, abort this procedure.

6. If animation’s hold time is resolved, let its start time be unresolved.

7. If has pending ready promise is false, let animation’s current ready promise be a new (pending) Promise object.

8. Schedule a task to run as soon as animation is ready. The task shall perform the following steps:

   1. Let ready time be the time value of the timeline associated with animation at the moment when animation became ready.

   2. If animation’s start time is unresolved, perform the following steps:

      1. Let new start time be the result of evaluating ready time - hold time / animation playback rate for animation. If the animation playback rate is zero, let new start time be simply ready time.

      2. If animation’s playback rate is not 0, make animation’s hold time unresolved.

      3. Set the animation start time of animation to new start time.

   3. Resolve animation’s current ready promise with animation.

   4. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false.

      Note that the order of the above two steps is important since it means that an animation with zero-length target effect will resolve its current ready promise before its current finished promise.

      So long as the above task is scheduled but has yet to run, animation is described as having a pending play task.

      A user agent MAY execute the above task immediately (if it determines animation is immediately ready) thereby bypassing the pending play state altogether.

9. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false.

3.5.10. Pausing an animation

Whenever an animation has an unresolved start time, its current time will be suspended.

As with playing an animation, pausing may not happen instantaneously (see §3.5.6 Waiting for the target effect). For example, if animation is performed by a separate process, it may be necessary to synchronize the current time to ensure that it reflects the state drawn by the animation process.

The procedure to pause an animation, animation, is as follows:

1. If animation has a pending pause task, abort these steps.

2. If the play state of animation is paused, abort these steps.

3. If the animation’s current time is unresolved, perform the steps according to the first matching condition from below:

   If animation’s playback rate is ≥ 0,

   Let animation’s hold time be zero.

   Should we throw an exception for playback rate = 0?

   Otherwise,

   If target effect end for animation is positive infinity, throw an InvalidStateError and abort these steps. Otherwise, let animation’s hold time be target effect end.

4. Let has pending ready promise be a boolean flag that is initially false.

5. If animation has a pending play task, cancel that task and let has pending ready promise be true.

6. If has pending ready promise is false, set animation’s current ready promise to a new (pending) Promise object.

7. Schedule a task to be executed at the first possible moment after the user agent has performed any processing necessary to suspend the playback of animation’s target effect, if any. The task shall perform the following steps:

   1. If animation’s start time is resolved, let animation’s hold time be the result of evaluating ready time - (start time / playback rate).

      Note: If we start playing an animation from the idle state, we will set the hold time to a suitable value while the animation is pending but leave the start time unresolved. The check here for an unresolved start time here ensures we preserve the hold time when aborting a pending play.

   2. Make animation’s start time unresolved.

   3. Resolve animation’s current ready promise with animation.

   4. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false.

   So long as the above task is scheduled but has yet to run, animation is described as having a pending pause task. While the task is running, however, animation does not have a pending pause task.

8. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false.

3.5.11. Reaching the end

This section is non-normative

DVD players or cassette players typically continue playing until they reach the end of their media at which point they stop. If such players are able to play in reverse, they typically stop playing when they reach the beginning of their media. In order to emulate this behavior and to provide consistency with HTML’s media elements [HTML5], the current time of Web Animations' animations do not play forwards beyond the end time of their target effect or play backwards past time zero.

An animation that has reached the natural boundary of its playback range is said to have finished.

Graphically, the effect of limiting the current time is shown below.

The effect of limiting the current time of an animation with a start time of 1s, a target effect of length 3s, and a positive animation playback rate. After the current time of the animation reaches the end of the target effect, it is capped at 3s.

It is possible, however, to seek the current time of an animation to a time past the end of the target effect. When doing so, the current time will not progress but the animation will act as if it had been paused at the seeked time.

This allows, for example, seeking the current time of an animation with no target effect to 5s. If target effect with an end time later than 5s is later associated with the animation, playback will begin from the 5s mark.

Similar behavior to the above scenario may arise when the length of an animation’s target effect changes.

Similarly, when the animation playback rate is negative, the current time does not progress past time zero.

3.5.12. The current finished promise

Each animation has a current finished promise. The current finished promise is initially a pending Promise object.

The object is replaced with a new (pending) Promise object every time the animation leaves the finished play state.

3.5.13. Updating the finished state

For an animation with a positive playback rate, the current time continues to increase until it reaches the target effect end.

The target effect end of an animation is equal to the end time of the animation’s target effect. If the animation has no target effect, the target effect end is zero.

An animation with a negative playback rate, the current time continues to decrease until it reaches zero.

A running animation that has reached this boundary (or overshot it) and has a resolved animation start time is said to be finished.

The crossing of this boundary is checked on each modification to the animation object using the procedure to update an animation’s finished state defined below. This procedure is also run on each sample and each time the timing properties of the target effect associated with an animation are updated.

At least with regards to resolving promises / dispatching finish events, it might be better to queue a task for that, and if the animation is still finished when the task runs, resolve the promise / dispatch the event. That way scripts don’t need to be so careful about the order in which they make timing changes.

For each animation, the user agent maintains a previous current time time value that is originally unresolved, and a previous finished state boolean flag that is initially false.

Whilst during normal playback the current time of an animation is limited to the boundaries described above, it is possible to seek the current time of an animation to times outside those boundaries using the procedure to set the current time of an animation.

The procedure to update an animation’s finished state for animation, given a flag did seek (to indicate if the update is being performed after setting the current time), is as follows:

1. If both of the following conditions are true,

   • animation’s start time is resolved, and

   • animation does not have a pending play task or a pending pause task,

   then update animation’s hold time based on the first matching condition for animation from below, if any:

   If animation playback rate > 0 and current time is resolved and greater than or equal to target effect end,

   If did seek is true, let the hold time be the value of current time.

   If did seek is false, let the hold time be the maximum value of previous current time and target effect end. If the previous current time is unresolved, let the hold time be target effect end.

   If animation playback rate < 0 and current time is resolved and less than or equal to 0,

   If did seek is true, let the hold time be the value of current time.

   If did seek is false, let the hold time be zero.

   If current time is resolved, and animation playback rate ≠ 0, and animation is associated with an active timeline,

   Perform the following steps:

   1. If did seek is true and the hold time is resolved, let animation’s start time be equal to the result of evaluating timeline time - (hold time / playback rate) where timeline time is the current time value of timeline associated with animation.

   2. Let the hold time be unresolved.

2. Let current finished state be true if the play state of animation is finished. Otherwise, let it be false.

3. If current finished state is true and previous finished state is false, resolve animation’s current finished promise object with animation.

4. If current finished state is false and previous finished state is true, set animation’s current finished promise to a new (pending) Promise object.

5. Set animation’s previous finished state to current finished state.

6. Set the previous current time of animation be the result of calculating its current time.

3.5.14. Finishing an animation

An animation can be advanced to the natural end of its current playback direction by using the procedure to finish an animation for animation defined below:

1. If animation playback rate is zero, or if animation playback rate > 0 and target effect end is infinity, throw an InvalidStateError and abort these steps.

2. Set limit as follows:

   If animation playback rate > 0,

   Let limit be target effect end.

   Otherwise,

   Let limit be zero.

3. Set the current time to limit.

   The procedure for setting the current time has the side effect of cancelling any pending pause task so we don’t need to handle that here.

4. If animation’s start time is unresolved and animation has an associated active timeline, let the start time be the result of evaluating timeline time - (limit / playback rate) where timeline time is the current time value of the associated timeline.

5. If there is a pending play task and start time is resolved, cancel that task and resolve the current ready promise of animation with animation.

6. Run the procedure to update an animation’s finished state animation with the did seek flag set to true.

Note: Finishing an animation does not necessarily cause that animation to enter the finished play state. In particular, if an animation was in the paused play state before finishing, it will remain in the paused play state afterwards.

3.5.15. Cancelling an animation

An animation can be cancelled which causes the current time to become unresolved hence removing any effects caused by the target effect.

The procedure to cancel an animation for animation is as follows:

1. Run the procedure to reset an animation’s pending tasks on animation.

2. Reject the current finished promise with a DOMException named "AbortError".

   If animation is already idle should we just keep the existing finished promise and not reject it? That seems more intuitive but the current behavior where cancel() always rejects the current finished promise might also be more useful/reliable?

3. Let current finished promise be a new (pending) Promise object.

4. Make animation’s hold time unresolved.

5. Make animation’s start time unresolved.

3.5.16. Speed control

Animations have a playback rate that provides a scaling factor from the rate of change of the associated timeline’s time values to the animation’s current time. The playback rate is initially 1.

Setting an animation’s playback rate to zero effectively pauses the animation (however, the play state does not necessarily become paused).

3.5.16.1. Updating the playback rate of an animation

Changes to the playback rate trigger a compensatory seek so that that the animation’s current time is unaffected by the change to the playback rate.

The procedure to set the animation playback rate of an animation, animation to new playback rate is as follows:

1. Let previous time be the value of the current time of animation before changing the playback rate.

2. Set the playback rate to new playback rate.

3. If previous time is resolved, set the current time of animation to previous time.

The procedure to silently set the animation playback rate of animation, animation to new playback rate is identical to the above procedure except that rather than invoking the procedure to set the current time in the final step, the procedure to silently set the current time is invoked instead.

3.5.17. Reversing an animation

The procedure to reverse an animation of animation animation is as follows:

1. If there is no timeline associated with animation, or the associated timeline is inactive throw an InvalidStateError and abort these steps.

2. Silently set the animation playback rate of animation to −animation playback rate.

   This must be done silently or else we may end up resolving the current ready promise when we do the compensatory seek despite the fact that we are most likely not exiting the pending play state.

3. Run the steps to play an animation for animation.

3.5.18. Play states

An animation may be described as being in one of the following play states for each of which, a non-normative description is also provided:

The play state of animation, animation, at a given moment is the state corresponding to the first matching condition from the following:

animation.effect.timing.duration = 5000;
animation.currentTime = 4000;
animation.pause();
animation.ready.then(function() {
  animation.effect.timing.duration = 3000;
  alert(animation.playState); // Displays 'paused'
  animation.startTime =
    document.timeline.currentTime - animation.currentTime * animation.playbackRate;
  alert(animation.playState); // Displays 'finished'
});

3.6. Animation effects

An animation effect is an abstract term referring to an item in the timing hierarchy.

3.6.1. Relationship between animation effects and animations

The target effect of an animation, if set, is a type of animation effect. The target effect of an animation is said to be associated with that effect. At a given moment, an animation effect can be associated with at most one animation.

An animation effect, effect, is associated with a timeline, timeline, if effect is associated with an animation which, in turn, is associated with timeline.

3.6.2. Types of animation effects

This specification defines a single type of animation effect: keyframe effects. Subsequent levels of this specification will define further types of animation effects. All types of animation effects define a number of common properties which are described in the following sections.

3.6.3. The active interval

The period that an animation effect is scheduled to run is called its active interval. Each animation effect has only one such interval.

The lower bound of the active interval typically corresponds to the start time of the animation associated with this animation effect but may be shifted by a start delay on the animation effect.

The upper bound of the interval is determined by the active duration.

The relationship between the start time, start delay, and active duration is illustrated below.

Examples of the effect of the start delay on the endpoints of the active interval.
(a) An animation effect with no delay; the start time and beginning of the active interval are coincident.
(b) An animation effect with a positive delay; the beginning of the active interval is deferred by the delay.
(c) An animation effect with a negative delay; the beginning of the active interval is brought forward by the delay.

An end delay may also be specified but is primarily only of use when sequencing animations.

Animation effects define an active interval which is the period of time during which the effect is scheduled to produce its effect with the exception of fill modes which apply outside the active interval.

The lower bound of the active interval is defined by the start delay.

The start delay of an animation effect is a signed offset from the start time of the animation with which the animation effect is associated

The length of the active interval is called the active duration, the calculation of which is defined in §3.9.2 Calculating the active duration.

Similar to the start delay, an animation effect also has an end delay which is primarily of use when sequencing animations based on the end time of another animation effect. Although this is typically only useful in combination with sequence effects which are introduced in a subsequent level of this specification, it is included here for the purpose of representing the min attribute in SVG ([SVG11], Chapter 19).

The end time of an animation effect is the result of calculating the following expression:

end time = max(start delay + active duration + end delay, 0).

3.6.4. Local time

The local time of an animation effect at a given moment is based on the first matching condition from the following:

3.6.5. Animation effect phases and states

This section is non-normative

At a given moment, an animation effect may be in one of three possible phases. If an animation effect has an unresolved local time it will not be in any phase.

The different phases are illustrated below.

An example of the different phases and states used to describe an animation effect.

The phases are as follows:

before phase

The animation effect’s local time falls before the effect’s active interval.

active phase

The animation effect’s local time falls inside the effect’s active interval.

after phase

The animation effect’s local time falls after the effect’s active interval.

In addition to these phases, an animation effect may also be described as being in one of several overlapping states. These states are only established for the duration of a single sample and are primarily a convenience for describing stative parts of the model.

These states and their useage within the model are summarised as follows:

in play

Corresponds to an animation effect whose active time is changing on each sample.

current

Corresponds to an animation effect that is either in play or may become in play in the future. This will be the case if the animation effect is in play or in its before phase, or it has an ancestor for which this is true thereby opening up the possibility that this animation effect might play again (e.g. due to repeating).

in effect

Corresponds to an animation effect that has a resolved active time. This occurs when either the animation effect is in its active phase or outside the active interval but at a time where the effect’s fill mode (see §3.7 Fill behavior) causes its active time to be resolved. Only in effect animation effects apply a result to their target.

The normative definition of each of these states follows.

An animation effect is in the before phase if the animation effect’s local time is not unresolved and is less than the effect’s start delay.

An animation effect is in the active phase if all of the following conditions are met:

1. the animation effect’s local time is not unresolved, and

2. the animation effect’s local time is greater than or equal to its start delay, and

3. the animation effect’s local time is less than the sum of its start delay and active duration.

An animation effect is in the after phase if the animation effect’s local time is not unresolved and is greater than or equal to the sum of its start delay and active duration.

An animation effect is in play if all of the following conditions are met:

1. the animation effect is in the active phase, and

2. the animation effect is associated with an animation that is not finished.

An animation effect is current if either of the following conditions is true:

• the animation effect is in the before phase, or

• the animation effect is in play.

An animation effect is in effect if its active time as calculated according to the procedure in §3.9.3.1 Calculating the active time is not unresolved.

3.7. Fill behavior

The effect of an animation effect when it is not in play is determined by its fill mode.

The possible fill modes are:

• none,

• forwards,

• backwards, and

• both.

The normative definition of these modes is incorporated in the calculation of the active time in §3.9.3.1 Calculating the active time.

3.7.1. Fill modes

This section is non-normative

The effect of each fill mode is as follows:

none

The animation effect has no effect when it is not in play.

forwards

When the animation effect is in the after phase, the animation effect will produce the same transformed time value as the last moment it is scheduled to be in play.

For all other times that the animation effect is not in play, it will have no effect.

backwards

When the animation effect is in the before phase, the animation effect will produce the same transformed time value as the earliest moment that it is scheduled to be in play.

For all other times that the animation effect is not in play, it will have no effect.

both

When the animation effect is in its before phase, backwards fill behavior is used.

When the animation effect is in its after phase, forwards fill behavior is used.

Some examples of the these fill modes are illustrated below.

Examples of various fill modes and the states produced.
(a) fill mode ‘none’. The animation effect has no effect outside its active interval.
(b) fill mode ‘forwards’. After the active interval has finished, the timed value continues to maintain a fill value.
(c) fill mode ‘backwards’. The animation effect produces a fill value until the start of the active interval.
(d) fill mode ‘both’. Both before and after the active interval the animation effect produces a fill value.

Note: setting a fill mode has no bearing on the endpoints of the active interval. However, the fill mode does have an effect on various other properties of the timing model since the active time of an animation effect is only defined (that is, not unresolved) inside the active interval or when a fill is applied.

Currently timing functions that generate results outside the range [0, 1] will behave unexpectedly when applied to group effects, as children will increase iterations or enter into fill mode rather than continuing to extrapolate along their defined behavior (which is what they would do if the timing function applied to them directly).

To fix this it is possible we will wish to introduce overflow fill modes that respond to time values larger than or smaller than the active time range by extrapolating rather than filling.

See section 15 (Overflowing fill) of minuted discussion from Tokyo 2013 F2F.

3.8. Repeating

3.8.1. Iteration intervals

It is possible to specify that an animation effect should repeat a fixed number of times or indefinitely. This repetition occurs within the active interval. The span of time during which a single repetition takes place is called an iteration interval.

Unlike the active interval, an animation effect can have multiple iteration intervals although typically only the interval corresponding to the current iteration is of interest.

The length of a single iteration is called the iteration duration. The initial iteration duration of an animation effect is zero.

This section is non-normative

Comparing the iteration duration and the active duration we have:

Iteration duration

The time taken for a single iteration of the animation effect to complete.

Active duration

The time taken for the entire animation effect to complete, including repetitions. This may be longer or shorter than the iteration duration.

The relationship between the iteration duration and active duration is illustrated below.

A comparison of the iteration duration and active duration of an animation effect with an iteration count of 2.5. Note that the iteration duration for the final iteration does not change, it is simply cut-off by the active duration.

3.8.2. Controlling iteration

The number of times an animation effect repeats is called its iteration count. The iteration count is a real number greater than or equal to zero. The iteration count may also be positive infinity to represent that the animation effect repeats indefinitely.

In addition to the iteration count, animation effects also have an iteration start property which specifies an offset into the series of iterations at which the animation effect should begin. The iteration start is a finite real number greater than or equal to zero.

The behavior of these parameters is defined in the calculations in §3.9 Core animation effect calculations.

This section is non-normative

The effect of the iteration count and iteration start parameters is illustrated below.

The effect of the iteration count and iteration start parameters.
In the first case the iteration count is 2.5 resulting in the third iteration being cut-off half way through its iteration interval.
The second case is the same but with an iteration start of 0.5. This causes the animation effect to begin half way through the first iteration.

Unlike the iteration count parameter, the iteration start parameter does not effect the length of the active duration.

Note that values of iteration start greater than or equal to one are generally not useful unless used in combination with an animation effect that has an iteration composite operation of accumulate.

3.8.3. Iteration time space

This section is non-normative

In Web Animations all times are relative to some point of reference. These different points of reference produce different time spaces.

This can be compared to coordinate spaces as used in computer graphics. The zero time of a time space is analogous to the origin of a coordinate space.

We can describe animations that repeat as establishing a new time space each time the animation repeats: the iteration time space.

Iteration time space is a time space whose zero time is the beginning of an animation effect’s current iteration.

Within the Web Animations model we also refer to active time which is a time relative to the beginning of the active interval. This time space, however, is internal to the model and not exposed in the programming interface or in markup.

These time spaces are illustrated below.

A comparison of local time, active time, and iteration time for an animation with a iteration duration of 1s and an iteration count of 2.5.

Note: While the time spaces themselves are not bounded, Web Animations defines active time and iteration time such that they are clamped to a set range as shown in the diagram. For example, whilst a time of -1 second is a valid time in active time space, the procedure for calculating the active time defined in §3.9.3.1 Calculating the active time will never return a negative value.

In addition to these time spaces we can also refer to the document time space which is time space of the time values of the default document timeline of the active document.

3.8.4. Interval timing

This section is non-normative

When an animation effect repeats we must define the behavior at the iteration boundaries. For this, and indeed for all interval timing, Web Animations uses an endpoint-exclusive timing model. This means that whilst the begin time of an interval is included in the interval, the end time time is not. In interval notation this can written [begin, end). This model provides sensible behavior when intervals are repeated and sequenced since there is no overlap between the intervals.

In the examples below, for the repeated effect, at local time 1s, the iteration time is 0. For the sequenced animations, at timeline time 1s, only animation B’s target effect will be in play; there is no overlap.

Illustration of end-point exclusive timing. For both repeated and sequenced animation effects there is no overlap at the boundaries between intervals.

An exception to this behavior is that when performing a fill, if the fill begins at an interval endpoint, the endpoint is used. This behavior falls out of the algorithm given in §3.9.3.3 Calculating the iteration time and is illustrated below.

After one iteration, the iteration time is 0, but after two iterations (and thereonwards), the iteration time is equal to the iteration duration due to the special behavior defined when an animation effect fills.

3.9. Core animation effect calculations

3.9.1. Overview

3.9.2. Calculating the active duration

The active duration is calculated as follows:

active duration = iteration duration × iteration count

If either the iteration duration or iteration count are zero, the active duration is zero.

This clarification is needed since the result of infinity multiplied by zero is undefined according to IEEE 754-2008.

3.9.3. Transforming the local time

3.9.3.1. Calculating the active time

The active time is based on the local time and start delay. However, it is only defined when the animation effect should produce an output and hence depends on its fill mode and phase as follows,

3.9.3.2. Calculating the scaled active time

Before the active time can be converted to an iteration time we must factor in the animation effect’s iteration start. The result is called the scaled active time.

In order to calculate the scaled active time we first define the start offset as follows:

start offset = iteration start × iteration duration

If the iteration start is zero, the start offset is zero.

Note: This clarification is needed since the iteration duration may be infinity and the result of infinity multiplied by zero is undefined according to IEEE 754-2008.

The scaled active time is calculated according to the following steps:

1. If the active time is unresolved, return an unresolved time value.

2. Return active time + start offset.

3.9.3.3. Calculating the iteration time

The iteration time is calculated according to the following steps:

1. If the scaled active time is unresolved, return unresolved.

2. If the iteration duration is zero, return zero.

3. If scaled active time - start offset is equal to the active duration, and iteration count is not zero, and (iteration count + iteration start) % 1 is zero, return the iteration duration.

4. Otherwise, return scaled active time % iteration duration.

3.9.4. Calculating the current iteration

The current iteration can be calculated using the following steps:

1. If the active time is unresolved, return unresolved.

2. If the active time is zero, return floor(iteration start).

   This is needed so that we report the correct current iteration when doing a backwards fill for an animation with a zero-length iteration duration.

3. If the iteration duration is zero,

   1. If the iteration count is infinity, return infinity.

   2. Otherwise, return ceil(iteration start + iteration count) - 1.

4. If the iteration time equals the iteration duration, return iteration start + iteration count - 1.

5. Return floor(scaled active time / iteration duration).

   If the iteration duration is infinity, the result of floor(scaled active time / iteration duration) will be zero as defined by IEEE 754-2008.

3.10. Direction control

Animation effects may also be configured to run iterations in alternative directions using direction control. For this purpose, animation effects have a playback direction parameter which takes one of the following values:

• normal,

• reverse,

• alternate, or

• alternate-reverse.

The semantics of these values are incorporated into the calculation of the directed time which follows.

3.10.1. Calculating the directed time

The directed time is calculated from the iteration time using the following steps:

1. If the iteration time is unresolved, return unresolved.

2. Calculate the current direction using the first matching condition from the following list:

   If playback direction is normal,

   Let the current direction be forwards.

   If playback direction is reverse,

   Let the current direction be reverse.

   Otherwise,

   1. Let d be the current iteration.

   2. If playback direction is alternate-reverse increment d by 1.

   3. There used to be a step here which seemed to be adding special handling for filling when the effect ends on a repeat boundary but it seems like that is taken care of by the calcuation of iteration time and current iteration. Is anything actually needed here?

   4. If d % 2 == 0, let the current direction be forwards, otherwise let the current direction be reverse. If d is infinity, let the current direction be forwards.

3. If the current direction is forwards then return the iteration time.

   Otherwise, return the iteration duration - iteration time.

3.11. Time transformations

3.11.1. Scaling the time

This section is non-normative

It is often desirable to control the rate at which an animation effect progresses. For example, easing the rate of animation can create a sense of momentum and produce a more natural effect. Conversely, in other situations such as when modelling a discrete change, a smooth transition is undesirable and instead it is necessary for the animation effect to progress in a series of distinct steps.

For such situations Web Animations provides timing functions that scale the progress of an animation effect.

Timing functions take an input progress value and produce a scaled output progress value.

Example of a timing function that produces an ease-in effect. Given an input progress of 0.7, the timing function scales the value to produce an output progress of 0.52.
By applying this timing function, time will appear to progress more slowly at first but then gradually progress more quickly.

Timing functions are applied to an iteration of an animation effect.

3.11.2. Timing functions

A timing function takes an input progress value in the range [0, 1] and produces an output progress value whose range is unbounded (i.e. positive and negative infinity are permitted).

Animation effects have one timing function associated with them. The default timing function is the linear timing function whose output is identical to its input. The linear timing function can be represented by the string “linear”.

The range of timing functions that may be applied to a given animation effects depends on the type of the animation effects.

3.11.3. Scaling using a cubic Bézier curve

This section is non-normative

A common method of producing easing effects is to use a cubic Bézier curve to scale the time. The endpoints of the curve are fixed at (0, 0) and (1, 1) while two control points P1 and P2 define the shape of the curve. Provided the x values of P1 and P2 lie within the range [0, 1] such a curve produces a function that is used to map input times (the x values) onto output times (the y values). This arrangement is illustrated below.

A cubic Bézier curve used as a timing function.
The shape of the curve is determined by the location of the control points P1 and P2.
Input progress values serve as x values of the curve, whilst the y values are the output progress values.

Some example cubic Bézier timing functions are illustrated below.

The timing functions produced by each of the keyword values associated with cubic Béier timing functions accepted by the easing member of the AnimationEffectTiming interface member from the programming interface.

A cubic Bézier timing function is a type of timing function defined by four real numbers that specify the two control points, P1 and P2, of a cubic Bézier curve whose end points are fixed at (0, 0) and (1, 1). The x coordinates of P1 and P2 are restricted to the range [0, 1].

The evaluation of this curve is covered in many sources such as [FUND-COMP-GRAPHICS].

A cubic Bézier timing function may be specified as a string using the following syntax (using notation from [CSS3VAL]):

<cubic-bezier-timing-function> = ease | ease-in | ease-out | ease-in-out | cubic-bezier(<number>, <number>, <number>, <number>)

The meaning of each value is as follows:

ease

Equivalent to cubic-bezier(0.25, 0.1, 0.25, 1).

ease-in

Equivalent to cubic-bezier(0.42, 0, 1, 1).

ease-out

Equivalent to cubic-bezier(0, 0, 0.58, 1).

ease-in-out

Equivalent to cubic-bezier(0.42, 0, 0.58, 1).

cubic-bezier(<number>, <number>, <number>, <number>)

Specifies a cubic Bézier timing function. The four numbers specify points P1 and P2 of the curve as (x1, y1, x2, y2). Both x values must be in the range [0, 1] or the definition is invalid.

cubic-bezier( [ <number>{6} ; ]* <number>{4} )

3.11.4. Timing in discrete steps

This section is non-normative It is possible to scale an animation effect’s timing so that the group effect occurs in a series of discrete steps using a stepping function.

Some example step timing functions are illustrated below.

Example step timing functions. In each case the domain is the input progress whilst the range represents the output progress produced by the step function.
The first row shows the function for each transition point when only one step is specified whilst the second row shows the same for three steps.

A step timing function is a type of timing function that divides the input time into a specified number of intervals that are equal in duration. The output time, starting at zero, rises by an amount equal to the interval duration once during each interval at the transition point which may be either the start, midpoint, or end of the interval.

In keeping with Web Animations' model of endpoint exclusive interval timing (see §3.8.4 Interval timing), the output time at the transition point is the time after applying the increase (i.e. the top of the step) with the following exception.

When a transition point coincides with the end of the active interval extra care must be taken to produce the correct result when performing a fill. To achieve this, when a step timing function is applied to an animation effect or applied to an animation effect associated with an animation effect, an additional before flag is passed. The value of the before flag is determined as follows:

1. If the active time of the animation effect is unresolved, the before flag is not set and these steps should be aborted.

2. Determine the current direction using the procedure defined in §3.10.1 Calculating the directed time.

3. If the current direction is forwards, let going forwards be true, otherwise it is false.

4. The before flag is set if the animation effect is in the before phase and going forwards is true; or if the animation effect is in the after phase and going forwards is false.

When a step timing function is evaluated at a transition point, if the before flag is set the result is the value before applying the increase.

A step timing function may be specified as a string using the following syntax:

<step-timing-function> = step-start | step-middle | step-end | steps(<integer>[, [ start | middle | end ] ]?)

The meaning of each value is as follows:

step-start

Equivalent to steps(1, start);

step-middle

Equivalent to steps(1, middle);

step-end

Equivalent to steps(1, end);

steps(<integer>[, [ start | middle | end ] ]?)

Specifies a step timing function. The first parameter specifies the number of intervals in the function. It must be a positive integer (greater than 0). The second parameter, which is optional, specifies the point at which the change of values occur within the interval. If the second parameter is omitted, it is given the value end.

3.11.5. Calculating the transformed time

The transformed time is calculated from the directed time using the following steps:

1. If the directed time is unresolved, return an unresolved time value.

2. If the iteration duration is infinity, return the directed time.

3. Let unscaled progress be the result of evaluating directed time / iteration duration unless iteration duration is zero, in which case let unscaled progress be zero.

4. Let scaled progress be the result of evaluating the animation effect’s timing function with unscaled progress as the input progress.

5. Return the result of evaluating scaled progress × iteration duration. If the scaled progress is zero, let the result be zero.

   Note: This clarification is needed since the iteration duration may be infinity and the result of infinity multiplied by zero is undefined according to IEEE 754-2008.

3.11.6. Calculating the iteration progress

Before the transformed time is passed to the animation model, it is normalized to represent a fraction of the iteration duration, known as a iteration progress.

The iteration progress of an animation effect is calculated by running the steps corresponding to the first matching condition from the following:

Note: Since timing functions are allowed to produce output progress values outside the range [0, 1] it is possible that the value calculated for the iteration progress also lies outside this range.

4. Animation Model

4.1. Keyframe effects

Keyframe effects are a kind of animation effect that use the output of the timing model to update CSS properties and DOM attributes of an element or pseudo-element such as ::before or ::after [SELECT] referred to as the target element.

Since the result of a keyframe effect is based on the iteration progress and current iteration value, it is updated whenever the timing model is updated including whenever it is sampled.

4.1.1. Target properties

Each keyframe effect can have zero or more associated target properties.

Target properties may be CSS properties or DOM attributes. If a given target element has an attribute with the same name as a CSS property, any target property of that name is taken to refer to to the CSS property.

Note: If there ever exists a situation where we need to animate an attribute with the same name as a property (other than a presentation attribute [SVG2]) then we will need to introduce a disambiguation strategy. Generally, however, such naming should be avoided.

4.1.2. Procedures for animating properties

Unless specifically defined otherwise, all properties are considered animatable. In order to animate a target property, the following procedures must be defined.

• interpolation — given two target property values V_start and V_end, produces an intermediate value V_res at a distance of p along the interval between V_start and V_end such that p = 0 produces V_start and p = 1 produces V_end. The range of p is (−∞, ∞) due to the effect of timing functions. As a result, this procedure must also define extrapolation behavior for p outside [0, 1].

• addition — given two target property values V_a and V_b, returns the sum of the two properties, V_result. For addition that is not commutative (for example, matrix multiplication) V_a represents the first term of the operation and V_b represents the second.

  This section is non-normative

  While addition can often be expressed in terms of the same weighted sum function used to define interpolation, this is not always the case. For example, interpolation of transform matrices involves decomposing and interpolating the matrix components whilst addition relies on matrix multiplication.

• accumulation — given two target property values V_a and V_b, returns the result, V_result, of combining the two operands such that V_b is treated as a delta from V_a. For accumulation that is not commutative (for example, accumulation of mismatched transform lists) V_a represents the first term of the operation and V_b represents the second.

  This section is non-normative

  For many types of animation such as numbers or lengths, accumulation is defined to be identical to addition.

  A common case where the definitions differ is for list-based types where addition may be defined as appending to a list whilst accumulation may be defined as component-based addition. For example, the filter list values "blur(2)" and "blur(3)", when added together may produce "blur(2) blur(3)", but when accumulated, may produce "blur(5)".

• distance computation — given two target property values V_start and V_end, calculates some notion of scalar distance between the values, distance.

4.1.3. Specific animation behaviors

The specific procedures used for animating a given target property are referred to as the property’s animation behavior.

The animation behavior of CSS properties is defined by the "Animatable:" line in the summary of the property’s definition or in [CSS3-TRANSITIONS] for properties that lack a such a line.

The default animation behavior for CSS properties is "as string". Should this be defined here or in CSS Animations Level 2?

For DOM attributes, the animation behavior is defined alongside the attribute definition. Unlike CSS properties, if such a definition is not provided the default animation behavior is “not animatable”.

Following is a series of pre-defined animation behaviors. [CSS3-TRANSITIONS] provides further CSS-specific animation behaviors.

For animation behaviors that do not define a specific procedure for addition or which are defined as not additive, the addition procedure is simply V_res = V_b.

For animation behaviors that do not define a specific procedure for accumulation, the accumulation procedure is identical to the addition procedure for that behavior.

For animation behaviors that do not define a specific procedure for distance computation or which are defined as not paceable, the distance computation procedure is simply distance = 1.

4.1.3.1. Not animatable

Some properties are specifically defined as not animatable. For example, properties defining animation parameters are not animatable since doing so would create complex recursive behavior.

Unlike other animation behaviors, no procedures for interpolation, addition and distance computation are defined for properties whose animation behavior is not animatable since these properties should not be modified.

An animation effect that targets a property that is not animatable will still exhibit the usual behavior for an animation effect such as delaying the fulfilment of an animation’s current finished promise.

4.1.3.2. Animatable as string

A target property that is animatable as string has the following animation behavior:

• interpolation:

  $V_{\mathrm{res}}=\left\{\begin{array}{cc}{V}_{\mathrm{start}}\hfill & \text{if }p<0.5\hfill \\ V_{\mathrm{end}}\hfill & \text{if }p\ge 0.5\hfill \end{array}\right.$

  V_res = V_start, if p < 0.5 or V_end, if p ≥ 0.5

4.1.3.3. Animatable as real number

A target property that is animatable as real number has the following animation behavior:

• interpolation: V_res = (1 - p) × V_start + p × V_end

• addition: V_a + V_b

• distance computation: distance = |V_end - V_start|

4.1.3.4. Animatable as length, percentage, or calc

A target property that is animatable as length, percentage, or calc has the following animation behavior:

• interpolation: as defined in [CSS3-TRANSITIONS].

• addition: calc(V_a + V_b)
  (Nested calc() functions are expanded when determining the computed value as defined in CSS Values and Units [CSS3VAL].)

• distance computation: as with animatable as real number but using the used value [CSS21] for V_start and V_end.

  When there is insufficient context to calculate a used value for all possible values of V_start and V_end, the result of the distance computation calculation is 1 (i.e. the behavior degenerates to not paceable).

  For example, for a keyframe effect that does not have an target element, there is no containing block for resolving percentage values against. As a result, the following code snippet falls back to not paceable animation behavior.

  var effect =
    new KeyframeEffect([ { top: '10%' },
                         { top: '20%' },
                         { top: '50%' } ],
                       { spacing: 'paced(top)'});
  // Prints '0, 0.5, 1'
  effect.getFrames().map(frame => frame.computedOffset).join(', ');

  For consistency, this definition applies even when a used value could be calculated for each of the animation values in question. As such, the following code fragment produces the same result.

  var effect =
    new KeyframeEffect([ { top: '10px' },
                         { top: '20px' },
                         { top: '50px' } ],
                       { spacing: 'paced(top)'});
  // Prints '0, 0.5, 1'
  effect.getFrames().map(frame => frame.computedOffset).join(', ');

4.1.3.5. Animatable as color

A target property that is animatable as color has the following animation behavior:

• interpolation: as defined in [CSS3-TRANSITIONS].

• addition: as with animatable as real number but performed on each RGBA color component in premultiplied space.

  Note: Since negative color is not currently supported, clamping of the channel values may be performed upon each addition or once when composition is complete.

• distance computation:

  $\mathrm{distance}=\sqrt{{\left(R_{\mathrm{end}}-R_{\mathrm{start}}\right)}^2+{\left(G_{\mathrm{end}}-G_{\mathrm{start}}\right)}^2+{\left(B_{\mathrm{end}}-B_{\mathrm{start}}\right)}^2+{\left(A_{\mathrm{end}}-A_{\mathrm{start}}\right)}^2}$

  distance = sqrt((R_end - R_start)^2 + (G_end - G_start)^2 + (B_end - B_start)^2 + (A_end - A_start)^2)

  where <R|G|B|A_start|end> represents the red, green, blue, or alpha channel of V_start or V_end respectively. Each value is normalized to the [0.0, 1.0] range and expressed in premultiplied color space.

4.1.3.6. Animatable as transform list

A target property that is animatable as transform list has the following animation behavior:

• interpolation: as defined in Interpolation of Transforms [CSS3-TRANSFORMS].

• addition: performed by concatenating transform lists as ‘V_a V_b’.

• accumulation:

  1. Beginning at the end of each list, V_a and V_b, find the largest contiguous portion of each list where the corresponding list elements from each list have the same transform type. Call the matching portions from V_a and V_b, V_matching-a and V_matching-b respectively and likewise V_remainder-a and V_remainder-b for the non-matching parts.

     We should probably expand 2d functions to their 3d equivalents before matching?

  2. Let V_combined be a transform list combining V_matching-a and V_matching-b by adding the numeric components of each corresponding function.

     This needs to be more specific, e.g. when combining translate(20px) and translate(30px 10px) we have to expand the first function to translate(20px 0px) first. Probably need to define unit conversion too.

  3. The result of accumulation is a transform list created by adding the combined result with the non-matching portions of the two lists as follows: ‘V_remainder-a V_remainder-b V_combined’.

• distance computation: See issue below.

4.1.3.7. Other animation behaviors

The set of animation behaviors defined here may be extended by other specifications. For example, properties with using the <image> type are animated using the interpolation behavior defined in CSS Image Values and Replaced Content [CSS4-IMAGES].

4.1.4. Effect values

Given an iteration progress, a current iteration, and an underlying value, a keyframe effect produces an effect value for each animatable target property by applying the animation behavior appropriate to the property.

4.2. Keyframes

The effect values for a keyframe effect are calculated by interpolating between a series of property values positioned at fractional offsets. Each set of property values indexed by an offset is called a keyframe.

The offset of a keyframe is a value in the range [0, 1] or the special value null. The list of keyframes for a keyframe effect is loosely sorted by offset which means that for each keyframe in the list that has a keyframe offset that is not null, the offset is greater than or equal to the offset of the previous keyframe in the list with a keyframe offset that is not null, if any.

The behavior when keyframes overlap or have unsupported values is defined in §4.2.2 The effect value of a keyframe effect.

Each keyframe also has a timing function associated with it that is applied to the period of time between the keyframe on which it is specified and the next keyframe in the list. The timing function specified on the last keyframe in the list is never applied.

Each keyframe may also have a keyframe-specific composite operation that is applied to all values specified in that keyframe. The possible operations and their meanings are identical to those defined for the composite operation associated with the keyframe effect as a whole in §4.3.4 Effect composition. If no keyframe-specific composite operation is specified for a keyframe, the composite operation specified for the keyframe effect as a whole is used for values specified in that keyframe.

4.2.1. Spacing keyframes

This section is non-normative.

It is often useful to be able to provide a series of property values without having calculate the keyframe offset of each value in time but instead to rely on some automatic spacing.

For example, rather than typing:

elem.animate([ { color: 'blue', offset: 0 },
               { color: 'green', offset: 1/3 },
               { color: 'red', offset: 2/3 },
               { color: 'yellow', offset: 1 } ], 2000);

It should be possible to type the following and allow the user agent to calculate the offset of each keyframe:

elem.animate([ { color: 'blue' },
               { color: 'green' },
               { color: 'red' },
               { color: 'yellow' } ], 2000);

Web Animations provides spacing modes for this purpose. The default spacing mode for keyframe effects is “distribute” which produces the result described above.

The other spacing mode, “paced”, is useful when it is desirable to maintain an even rate of change such as for motion path animation.

For example, consider the following animation:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px' },
               { left: '50px' } ], 1000);

The resulting value of the left property is illustrated below:

The animated value of the left property over time when applying the distribute spacing mode. The values are evenly spaced in time but the rate of change differs for each segment as indicated the varying slope of the graph.

We can use the paced spacing mode as follows:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px' },
               { left: '50px' } ],
             { duration: 1000, spacing: "paced(left)" });

The result is illustrated below:

The animated value of the left property over time when applying the paced spacing mode. The absolute value of the slope is graph is equal for all segments of the animation indicating a constant rate of change.

It is also possible to combine fixed keyframe offsets with spacing modes as follows:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px', offset: 0.5 },
               { left: '50px' } ],
             { duration: 1000, spacing: "paced(left)" });

The result is illustrated below:

The animated value of the left property over time when applying the paced spacing mode and a fixed keyframe offset that puts the 100px value at 0.5. The slope of the graph is equal for the first two segments but changes for the last segment in order to accommodate the fixed offset.

Before calculating effect values from a keyframe effect, an absolute value must be computed for keyframe offset of each keyframe with a null offset.

The values computed depend on the keyframe spacing mode specified for the keyframe effect. The keyframe spacing modes are:

distribute

Indicates that keyframes with a null keyframe offset are positioned so that the difference between subsequent keyframe offsets are equal.

paced

Indicates that keyframes with a null keyframe offset are positioned so that the distance between subsequent values of a specified paced property are equal. The distance is calculated using the distance computation procedure defined by the animation behavior associated with the paced property.

Since the absolute value calculated for a keyframe offset may change depending on the keyframe values, the number of values, or external context (such as when using paced keyframe spacing mode in combination with percentage values or em-based units), the original null values are not overwritten, rather, the calculated absolute values are stored as a separate value on each keyframe known as its computed keyframe offset.

4.2.1.1. Applying spacing to keyframes

We define a generic procedure for evenly distributing a keyframe, keyframe, between two reference keyframes, start and end, whose computed keyframe offsets are not null, as follows:

1. Let offset_k be the computed keyframe offset of a keyframe k.

2. Let n be the number of keyframes between and including start and end minus 1.

3. Let index refer to the position of keyframe in the sequence of keyframes between start and end such that the first keyframe after start has an index of 1.

4. Set the computed keyframe offset of keyframe to offset_start + (offset_end − offset_start) × index / n.

The computed keyframe offset values of each keyframe are determined using the following procedure.

1. Let keyframes refer to the list of keyframes associated with the keyframe effect.

2. For each keyframe, in keyframes, let the computed keyframe offset of the keyframe be equal to its keyframe offset value.

3. If keyframes contains more than one keyframe and the computed keyframe offset of the first keyframe in keyframes is null, set the computed keyframe offset of the first keyframe to 0.

4. If the computed keyframe offset of the last keyframe in keyframes is null, set its computed keyframe offset to 1.

5. For each pair of keyframes A and B where:

   • A appears before B in keyframes, and

   • A and B have a computed keyframe offset that is not null, and

   • all keyframes between A and B have a null computed keyframe offset,

   calculate the computed keyframe offset of each keyframe between A and B depending on the keyframe spacing mode as follows:

   If the spacing mode is paced,

   1. Define a keyframe as paceable if it contains a value for the paced property.

   2. Let paced A be the first keyframe in the range [A, B] that is paceable, if any.

   3. Let paced B be the last keyframe in the range [A, B] that is paceable, if any.

   4. If there is no paced A or paced B let both refer to B.

      Note: In this case the spacing behavior degenerates to distribute spacing.

   5. For each keyframe in the range (A, paced A] and [paced B, B), apply the procedure for evenly distributing a keyframe using A and B as the start and end keyframes respectively.

      Yes, this is correct. We want, index and n in that procedure to reflect all the keyframes between A and B, not just the keyframes between, for example, A and spaced A.

   6. For each keyframe in the range (paced A, paced B) that is paceable:

      1. Let dist_k represent the cumulative distance to a keyframe k from paced A as calculated by applying the distance computation defined by the animation behavior of the paced property to the values of the paced property on each pair of successive paceable keyframes in the range [paced A, k].

      2. Set the computed keyframe offset of k to offset_{paced A} + (offset_{paced B} − offset_{paced A}) × dist_k / dist_{paced B}

   7. For each keyframe in the range (paced A, paced B) that still has a null computed keyframe offset (because it is not paceable), apply the procedure for evenly distributing a keyframe using the nearest keyframe before and after the keyframe in question in keyframes that has a computed keyframe offset that is not null, as the start and end keyframes respectively.

   Otherwise,

   Apply the procedure for evenly distributing a keyframe to each keyframe in the range (A, B) using A and B as the start and end keyframes respectively.

The above algorithm is quite complex. It attempts to cover all possible combinations of input where keyframe offsets and or paced property values may be missing. Furthermore, it attempts to do this in a way that degenerates consistently and also allows the author to combine fixed offsets with either pacing or distribute spacing. We await implementation experience to determine if the complexity is justified.

4.2.2. The effect value of a keyframe effect

The effect value of a single property referenced by a keyframe effect as one of its target properties, for a given iteration progress, current iteration and underlying value is calculated as follows.

1. Let target property be the property for which the effect value is to be calculated.

2. If animation behavior of the target property is not animatable abort this procedure since the effect cannot be applied.

3. Define the neutral value for composition as a value which, when combined with an underlying value using the add composite operation, produces the underlying value.

4. Let property-specific keyframes be a copy of the list of keyframes specified on the effect.

5. Remove any keyframes from property-specific keyframes that do not have a property value for target property.

6. If property-specific keyframes is empty, return underlying value.

7. If there is no keyframe in property-specific keyframes with a computed keyframe offset of 0, create a new keyframe with a computed keyframe offset of 0, a property value set to the neutral value for composition, and a composite operation of add, and prepend it to the beginning of property-specific keyframes.

8. Similarly, if there is no keyframe in property-specific keyframes with a computed keyframe offset of 1, create a new keyframe with a computed keyframe offset of 1, a property value set to the neutral value for composition, and a composite operation of add, and append it to the end of property-specific keyframes.

9. Let interval endpoints be an empty sequence of keyframes.

10. Populate interval points by following the steps from the first matching condition from below:

    If iteration progress < 0 and there is more than one keyframe in property-specific keyframes with a computed keyframe offset of 0,

    Add the first keyframe in property-specific keyframes to interval endpoints.

    If iteration progress ≥ 1 and there is more than one keyframe in property-specific keyframes with a computed keyframe offset of 1,

    Add the last keyframe in property-specific keyframes to interval endpoints.

    Otherwise,

    1. Append to interval endpoints the last keyframe in property-specific keyframes whose computed keyframe offset is less than or equal to iteration progress and less than 1. If there is no such keyframe (because, for example, the iteration progress is negative), add the last keyframe whose computed keyframe offset is 0.

    2. Append to interval endpoints the next keyframe in property-specific keyframes after the one added in the previous step.

11. For each keyframe in interval endpoints:

    1. If keyframe has a composite operation that is not replace, or keyframe has no composite operation and the composite operation of this keyframe effect is not replace, then perform the following steps:

       1. Let composite operation to use be the composite operation of keyframe, or if it has none, the composite operation of this keyframe effect.

       2. Let value to combine be the property value of target property specified on keyframe.

       3. Replace the property value of target property on keyframe with the result of combining underlying value (V_a) and value to combine (V_b) using the composite operation to use procedure defined by the target property’s animation behavior.

    2. If this keyframe effect has an iteration composite operation of accumulate, apply the following step current iteration times:

       • replace the property value of target property on keyframe with the result of combining the property value (V_a) with the property value on the final keyframe in property-specific keyframes (V_b) using the accumulation procedure defined for target property.

       It seems like this could be done as a separate step at the end and applied to all types of animation effects consistently.

12. If there is only one keyframe in interval endpoints return the property value of target property on that keyframe.

13. Let start offset be the computed keyframe offset of the first keyframe in interval endpoints.

14. Let end offset be the computed keyframe offset of last keyframe in interval endpoints.

15. Let interval distance be the result of evaluating (iteration progress - start offset) / (end offset - start offset)

16. Return the result of applying the interpolation procedure defined by the animation behavior of the target property, to the values of the target property specified on the two keyframes in interval endpoints taking the first such value as V_start and the second as V_end and using interval distance as the interpolation parameter p.

Note: this procedure permits overlapping keyframes. The behavior is that at the point of overlap the output value jumps to the value of the last defined keyframe at that offset. For overlapping frames at 0 or 1, the output value for iteration progress values less than 0 or greater than or equal to 1 is the value of the first keyframe or the last keyframe in keyframes respectively.

4.3. Combining effects

This section is non-normative

After calculating the effect values for a keyframe effect, they are applied to the animation effect’s target properties.

Since it is possible for multiple in effect keyframe effects to target the same property it is often necessary to combine the results of several keyframe effects together. This process is called compositing and is based on establishing an effect stack for each property targetted by an in effect animation effect.

After compositing the results of keyframe effects together, the composited result is combined with other values specified for the target property.

For a CSS target property the arrangement is illustrated below:

Overview of the application of effect values to their target properties.
The results of keyframe effects targetting the same property are composited together using an effect stack.
The result of this composition is then inserted into the CSS cascade at an appropriate point.

For a target property that specifies a DOM attribute, the composited result is combined with the value of the attribute specified in the DOM or the lacuna value for that attribute if it is not specified.

For the first part of this operation—combining effect values that target the same property— it is necessary to determine both how keyframe effects are combined with one another, as well as the order in which they are applied, that is, their relative priority.

The matter of how effect values are combined is governed by the composite operation of the corresponding keyframe effects.

The relative priority of effect values is determined by an effect stack established for each animated property.

4.3.1. Animation types

This specification provides a common animation model intended to be used by other specifications that define markup or programming interfaces on top of this model. The particular markup or programming interface that generated an animation defines its animation type.

Further specifications may define specialized behavior for prioritizing animations between types or within a particular type.

4.3.2. The effect stack

Associated with each property targetted by one or more keyframe effects is an effect stack that establishes the relative priority of the keyframe effects.

The relative priority of any two keyframe effects, A and B, within an effect stack is established by comparing their properties as follows:

1. Let the associated animation of an animation effect be the animation associated with the animation effect that affecting the property with which this effect stack is associated.

2. Sort A and B by applying the following conditions in turn until the order is resolved,

   1. If A and B’s associated animations differ by type, sort by any inter-type prioritization defined for the corresponding types.

   2. If A and B are still not sorted, sort by any type-specific prioritization defined by the common type of A and B’s associated animations.

   3. If A and B are still not sorted, sort by the animation sequence number of their associated animations so that lower sequence numbers sort first.

Animation effects that sort earlier have lower priority.

4.3.3. Calculating the result of an effect stack

In order to calculate the final value of an effect stack, the effect values of each keyframe effect in the stack are combined in order of priority from lowest to highest priority.

Each step in the process of evaluating an effect stack takes an underlying value as input.

For each keyframe effect in the stack, the appropriate effect value from the keyframe effect is combined with the underlying value to produce a new value. This resulting value becomes the underlying value for combining the next keyframe effect in the stack.

The final value of an effect stack, called the composited value, is simply the result of combining the effect value of the final (highest priority) keyframe effect in the stack with the underlying value at that point.

4.3.4. Effect composition

The specific operation used to combine an effect value with an underlying value is determined by the composite operation of the keyframe effect that produced the effect value.

This specification defines three composite operations as follows:

replace

The result of compositing the effect value with the underlying value is simply the effect value.

add

The effect value is added to the underlying value. For animation behaviors where the addition operation is defined such that it is not commutative, the order of the operands is underlying value + effect value.

accumulate

The effect value is accumulated onto the underlying value. For animation behaviors where the accumulation operation is defined such that it is not commutative, the order of the operands is underlying value followed by effect value.

4.3.5. Applying the composited result

The process for applying a composited value depends on if the target property refers to a CSS property or a DOM attribute.

4.3.5.1. Applying the composited result to a CSS property

Applying a composited value to a CSS target property is achieved by adding a specified value to the CSS cascade.

The level of the cascade to which this specified value is added depends on the type of the animation associated with the highest priority effect in the effect stack for a given property. By default, the specified value is added to the ‘Animation declarations’ level of the cascade ([css-cascade-3]).

The composited value calculated for a CSS target property is applied using the following process.

1. Calculate the base value of the property as the value generated for that property by computing the computed value for that property in the absence of animations.

2. Establish the effect stack for the property (see §4.3.2 The effect stack).

3. Calculate the composited value of the effect stack passing in the base value of the property as the initial underlying value (see §4.3.3 Calculating the result of an effect stack).

4. Insert the composited value into the CSS cascade at the level defined for the type of the animation associated with the effect at the top of the effect stack established for the target property.

4.3.5.2. Applying the composited result to a DOM attribute

DOM attributes are, unless otherwise specified, not animatable. For each attribute that has a specific animation behavior associated with it, an attribute value to use when the attribute is not specified or in error must be defined, referred to as the lacuna value. For example, SVG2 ([SVG2]) defines lacunae values for its attributes.

The composited value calculated for a DOM attribute target property is applied using the following process.

1. Let the base value of the property be the value specified for attribute in the DOM or, if the attribute value is not specified in the DOM, the lacuna value for that attribute.

2. Establish the effect stack for the property (see §4.3.2 The effect stack).

3. Calculate the composited value of the effect stack passing in the base value of the attribute as the initial underlying value (see §4.3.3 Calculating the result of an effect stack).

4. Record the composited value as the animated attribute value of the attribute.

The animated attribute value does not replace the value of the attribute in the DOM although it may be accessible via some other interface. For all intents and purposes other than querying attributes values using DOM interfaces, user agents must treat the animated attribute value as the attribute value.

4.3.6. Effect accumulation

Similar to the compositing performed between effect values (see §4.3.4 Effect composition), the iteration composite operation determines how values are combined between successive iterations of the same keyframe effect.

This specification defines two iteration composite operations as follows:

replace

Each successive iteration is calculated independently of previous iterations.

accumulate

Successive iterations of the animation are accumulated with the final value of the previous iteration.

The application of the iteration composite operation is incorporated in the calculation of the effect value in §4.2.2 The effect value of a keyframe effect.

5. Programming interface

5.1. Time values in the programming interface

Time values are represented in the programming interface with the type double. Unresolved time values are represented by the value null.

5.2. The AnimationTimeline interface

Timelines are represented in the Web Animations API by the AnimationTimeline interface.

interface AnimationTimeline {
    readonly attribute double? currentTime;
    sequence<Animation> getAnimations();
};

[Constructor (DOMHighResTimeStamp originTime)]
interface DocumentTimeline : AnimationTimeline {
};

[Constructor (optional AnimationEffectReadOnly? effect = null,
              optional AnimationTimeline? timeline = null)]
interface Animation {
             attribute AnimationEffectReadOnly? effect;
             attribute AnimationTimeline?       timeline;
             attribute double?                  startTime;
             attribute double?                  currentTime;
             attribute double                   playbackRate;
    readonly attribute AnimationPlayState       playState;
    readonly attribute Promise<Animation>       ready;
    readonly attribute Promise<Animation>       finished;
    void cancel ();
    void finish ();
    void play ();
    void pause ();
    void reverse ();
};

enum AnimationPlayState { "idle", "pending", "running", "paused", "finished" };

interface AnimationEffectReadOnly {
    readonly attribute AnimationEffectTimingReadOnly timing;
    readonly attribute ComputedTimingProperties      computedTiming;
};

interface AnimationEffectTimingReadOnly {
    readonly attribute double                             delay;
    readonly attribute double                             endDelay;
    readonly attribute FillMode                           fill;
    readonly attribute double                             iterationStart;
    readonly attribute unrestricted double                iterations;
    readonly attribute (unrestricted double or DOMString) duration;
    readonly attribute PlaybackDirection                  direction;
    readonly attribute DOMString                          easing;
};

interface AnimationEffectTiming : AnimationEffectTimingReadOnly {
    inherit attribute double                             delay;
    inherit attribute double                             endDelay;
    inherit attribute FillMode                           fill;
    inherit attribute double                             iterationStart;
    inherit attribute unrestricted double                iterations;
    inherit attribute (unrestricted double or DOMString) duration;
    inherit attribute PlaybackDirection                  direction;
    inherit attribute DOMString                          easing;
};

dictionary AnimationEffectTimingProperties {
    double                             delay = 0;
    double                             endDelay = 0;
    FillMode                           fill = "auto";
    double                             iterationStart = 0.0;
    unrestricted double                iterations = 1.0;
    (unrestricted double or DOMString) duration = "auto";
    PlaybackDirection                  direction = "normal";
    DOMString                          easing = "linear";
};

dictionary ComputedTimingProperties : AnimationEffectTimingProperties {
    unrestricted double  endTime;
    unrestricted double  activeDuration;
    double?              localTime;
    unrestricted double? progress;
    unrestricted double? currentIteration;
};

enum FillMode { "none", "forwards", "backwards", "both", "auto" };

enum PlaybackDirection { "normal", "reverse", "alternate", "alternate-reverse" };

[Constructor (Animatable? target,
              (PropertyIndexedKeyframe or sequence<Keyframe> or SharedKeyframeList) frames,
              optional (unrestricted double or KeyframeEffectOptions) options)]
interface KeyframeEffectReadOnly : AnimationEffectReadOnly {
    readonly attribute Animatable?                 target;
    readonly attribute IterationCompositeOperation iterationComposite;
    readonly attribute CompositeOperation          composite;
    readonly attribute DOMString                   spacing;
    KeyframeEffect             clone();
    sequence<ComputedKeyframe> getFrames ();
};

[Constructor (Animatable? target,
              (PropertyIndexedKeyframe or sequence<Keyframe> or SharedKeyframeList) frames,
              optional (unrestricted double or KeyframeEffectOptions) options)]
interface KeyframeEffect : KeyframeEffectReadOnly {
    inherit attribute Animatable?                 target;
    inherit attribute IterationCompositeOperation iterationComposite;
    inherit attribute CompositeOperation          composite;
    inherit attribute DOMString                   spacing;
    void setFrames ((PropertyIndexedKeyframe or sequence<Keyframe> or SharedKeyframeList) frames);
};

dictionary KeyframeEffectOptions : AnimationEffectTimingProperties {
    IterationCompositeOperation iterationComposite = "replace";
    CompositeOperation          composite = "replace";
    DOMString                   spacing = "distribute";
};

var effect = new KeyframeEffect(elem, { left: '100px' }, 3000);

// Specify multiple properties at once
var effectA = new KeyframeEffect(elem, { left: '100px', top: '300px' }, 3000);

// Specify multiple frames
var effectB = new KeyframeEffect(elem, [ { left: '100px' }, { left: '300px' } ], 3000);

var effect =
  new KeyframeEffect(elem, { left: '100px' }, { duration: 3000, delay: 2000 });

var effect = new KeyframeEffect(elem, { display: 'none' }, { fill: 'forwards' });

elem.animate({ left: '100px' }, 3000);

enum IterationCompositeOperation {"replace", "accumulate"};

enum CompositeOperation {"replace", "add", "accumulate"};

dictionary Keyframe {
    // ... property-value pairs ...
    double?             offset = null;
    DOMString           easing = "linear";
    CompositeOperation? composite = null;
};

// The following two expressions produce the same result:
elem.animate([ { color: 'blue' },
               { color: 'green' },
               { color: 'red' },
               { color: 'yellow' } ], 2000);
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow' ] }, 2000);

// Likewise, for a multi-property animation, the following two
// expressions are equivalent:
elem.animate([ { color: 'blue', left: '0px' },
               { color: 'green', left: '-20px' },
               { color: 'red', left: '100px' },
               { color: 'yellow', left: '50px'} ], 2000);
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow' ],
               left: [ '0px', '-20px', '100px', '50px' ] }, 2000);

// Incidentally, the following three expressions are all equivalent:
elem.animate([ { color: 'red' } ], 1000);
elem.animate({ color: [ 'red' ] }, 1000);
elem.animate({ color: 'red' }, 1000);

dictionary PropertyIndexedKeyframe {
    // ... property-value and property-valuelist pairs ...
    DOMString           easing = "linear";
    CompositeOperation? composite = null;
};

dictionary ComputedKeyframe : Keyframe {
    double computedOffset;
};

var keyframes = new SharedKeyframeList([
 { left: '100px', backgroundColor: 'red' },
 { left: '200px', backgroundColor: 'green', offset: 0.4 },
 { left: '400px', backgroundColor: 'blue' } ]);
var player1 = element1.animate(keyframes, 1000);
var player2 = element2.animate(keyframes, { duration: 1000, delay: 1000 });

[Constructor ((PropertyIndexedKeyframe or sequence<Keyframe> or SharedKeyframeList) frames)]
interface SharedKeyframeList {
};

[NoInterfaceObject]
interface Animatable {
    Animation           animate ((PropertyIndexedKeyframe or sequence<Keyframe> or SharedKeyframeList) frames,
                                 optional (double or KeyframeEffectOptions) options);
    sequence<Animation> getAnimations ();
};

partial interface Document {
    readonly attribute DocumentTimeline timeline;
};

Element implements Animatable;

elem.animate({ color: 'red' }, 2000);

PseudoElement implements Animatable;