Web Animations 1.0

3.4.1 The document timeline

Each document has a timeline called the document timeline. The time values of the document timeline are calculated as a fixed offset from the global clock such that the zero time corresponds to the navigationStart moment [NAVIGATION-TIMING]. Prior to this moment, the document timeline is not started.

3.5.1 The current time of a player

Players provide a time value to their source content called the player's current time.

The calculation of the current time is as follows:

current time = (timeline time - start time) × playback rate

unless the hold time is not null, in which case the current time is equal to the hold time.

Where:

• timeline time is the current time value of the timeline with which this player is associated.
• start time is the player's start time.
• playback rate is the player's playback rate value described in section 3.5.3 Speed control.
• hold time is the value described in section 3.5.2.4 Seeking, pausing and limiting properties.

The procedure for performing manual updates to the current time is defined in section 3.5.2.9 Performing a seek.

If the timeline with which the player is associated is not started, then the current time is null.

It is often useful to manipulate the current time of a player even when its associated timeline is not started. For example, this is useful for pre-seeking a player. For this purpose, we have the following additional definitions:

effective timeline time

The current time value of the timeline associated with a player unless the timeline is not started, in which case the effective timeline time is zero.

effective current time

The result of evaluating the current time as above but substituting the effective timeline time for the timeline time.

3.5.2 Seeking, pausing and limiting

Seeking, pausing and limiting a player are closely related and are described here together.

3.5.2.1 Introduction to seeking

This section is non-normative.

Changing the current playback position of a player, that is, its current time, can be used to rewind its source content to its start point, fast-forward to a point in the future, or to provide ad-hoc synchronization between players.

Changing the current time of a player has the side effect of shifting its start time as illustrated below.

At time t, a seek is performed on the player changing its current time from 1.5s to 2s.

It is possible to seek a player even if its timeline is not started. Once the timeline begins, the player will begin playback from the seeked time.

3.5.2.2 Introduction to pausing

This section is non-normative.

Pausing can be used to temporarily suspend a player. Like seeking, pausing controls the current time of a player by updating its start time. The result is illustrated below.

The effect of pausing a player.
Whether pausing before or after a player's start time, the player's start time is delayed by the duration of the interval during which it was paused.

3.5.2.3 Limiting the current time

This section is non-normative.

Players in the real world such as 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' players do not play forwards beyond the end time of their source content or play backwards past time zero. This behavior is called limiting.

Graphically, the effect of limiting is shown below.

The effect of limiting on a player with a start time of 1s, a source content of length 3s, and a positive player playback rate. After the current time of the player reaches the end of the source content, it is capped at 3s.

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

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

Similar behavior to the above scenarios may arise when the length of a player's source content changes.

When the player playback rate is negative, the current time does not progress past time zero although it may be seeked to a negative time.

Limiting the current time acts like a sort of automatic pausing and is accomplished using the same machinery as pausing.

3.5.3 Speed control

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

Setting a player's playback rate to zero effectively pauses the player but without affecting the player's paused state.

3.5.4 Player events

As players play they report changes to their status through player events.

Player events are a property of the Web Animations timing model. As a result they are dispatched even when the source content of the player is absent or has no observable result.

3.6.1 Relationship between animation nodes and players

The source content of a player, if set, is a type of animation node. The source content of a player is said to be directly associated with that player.

Animation nodes can be combined together into a hierarchy using animation groups (see section 3.13 Grouping and synchronization). Only the root animation node of such a hierarchy can be directly associated with a player. If an animation node that has a parent animation group is designated as the source content of a player, the animation node is removed from its parent animation group before being associated with the player.

An animation node is associated with a player if it is directly associated with a player or if it has an ancestor animation group that is directly associated with a player. At a given moment, an animation node can be associated with at most one player.

An animation node, node, is associated with a timeline, timeline, if node is associated with a player which, in turn, is associated with timeline.

3.6.2 Types of animation nodes

This specification defines two types of animation nodes:

• animations, and
• animation groups.

All types of animation nodes define a number of common properties which are described in the following sections.

3.6.3 The active interval

This section is non-normative.

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

The lower bound of the active interval is determined by the start time of the animation node but may be shifted by a start delay on the animation node.

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 node with no delay; the start time and beginning of the active interval are coincident.
(b) An animation node with a positive delay; the beginning of the active interval is deferred by the delay.
(c) An animation node 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 such as by using a sequence animation group.

Animation nodes define an active interval which is the period of time during which the node 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 combination of the animation node's start time and start delay.

An animation node's start time is the moment at which the parent animation group, if any, has scheduled the animation node to begin. It is expressed in inherited time. In most cases, including the case when the animation node has no parent animation group, the start time is zero. The singular exception is sequence animation groups which set the start times of their children as described in section 3.13.4.1 The start time of children of an animation sequence.

In addition to the start time, an animation node also has a start delay which is an offset from the start time. Unlike the start time which is determined by the parent animation group, the start delay is a property of the animation node itself.

The lower bound of the active interval of an animation node, expressed in inherited time space, is the sum of the start time and the start delay.

These definitions are incorporated in the calculation of the local time (see section 3.6.4 Local time and inherited time) and active time.

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

Similar to the start delay, an animation node also has an end delay which may be used to delay the start time of the next sibling in a sequence animation group.

3.6.4 Local time and inherited time

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.

Just as with coordinate spaces, time spaces can also be nested. Animation groups typically perform some transformations on the time values they receive from their parent or player before passing on the transformed time values to their children. Child animation nodes then operate within that transformed time space.

Children take the transformed time values from their parent—called the inherited time— and add their start time to establish their own local time space as illustrated below.

Inherited time and local time.
At time t, the inherited time is 2.5.
For animation node (a) which has a start time of 1, the local time is 1.5.
For animation node (b) which has a start time of 1 and a start delay of 1, the local time is also 1.5 since local time is based on an animation node's start time only, and not on its start delay.

For an animation node, the inherited time at a given moment is based on the first matching condition from the following:

If the animation node has a parent animation group,

the inherited time is the parent animation group's current transformed time.

If the animation node is directly associated with a player,

the inherited time is the current time of the player.

Otherwise,

the inherited time is null.

The local time of an animation node is the animation node's inherited time minus its start time. If the inherited time is null then the local time is also null.

3.6.5 Animation node phases and states

This section is non-normative.

At a given moment, an animation node may be in one of three possible phases. If an animation node has a null 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 node.

The phases are as follows:

before phase

The animation node's local time falls before the node's active interval.

active phase

The animation node's local time falls inside the node's active interval.

after phase

The animation node's local time falls after the node's active interval.

In addition to these phases, an animation node 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 node whose active time is changing on each sample. This occurs when the animation node and all its ancestors are in the active phase. Animations only “move” when they are in play.

It is possible for an animation node to be in the active phase but not in play. For example, if an animation node has a parent animation group that causes the animation node's active interval to be clipped and both parent and child apply the same fill mode, the child animation node may be effectively be snapshotted within the active phase despite no longer being in play.

current

Corresponds to an animation node that is either in play or may become in play in the future. This will be the case if the animation node 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 node might play again (e.g. due to repeating).

This state is used in the programming interface to identify all animations and players that are likely to be of interest.

Furthermore, the current state provides an important definition for managing the amount of memory required by implementations. Assuming a monotonically increasing timeline an implementation can safely discard all animation nodes that are not current and not referenced elsewhere provided they take care to preserve any fill values. This is because such animation nodes will no longer have any dynamic effect.

in effect

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

The normative definition of each of these states follows.

An animation node is in the before phase if the animation node's local time is not null and is less than the node's start delay.

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

1. the animation node's local time is not null, and
2. the animation node's local time is greater than or equal to its start delay, and
3. the animation node's local time is less than the sum of its start delay and active duration.

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

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

1. the animation node is in the active phase, and
2. the animation node has a parent animation group that is in play or else is directly associated with a player that is not limited.

An animation node is current if it any of the following conditions is true:

• it is in the before phase, or
• it is in play, or
• it has a parent animation group and the parent animation group is current.

An animation node is in effect if its active time as calculated according to the procedure in section 3.10.3.1 Calculating the active time is not null.

3.8.1 Iteration intervals

It is possible to specify that an animation node 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 node 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 node is simply its intrinsic iteration duration.

The intrinsic iteration duration of an animation node is zero, however some specific types of animation node such as animation groups override this behavior and provide an alternative intrinsic duration (see section 3.13.3 The intrinsic iteration duration of an animation group and section 3.13.4.2 The intrinsic iteration duration of an animation sequence).

The iteration duration of an animation node may be set by the author to represent a value other than the intrinsic iteration duration.

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 node to complete.

Active duration

The time taken for the entire animation node 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 node 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 node 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 node repeats indefinitely.

In addition to the iteration count, animation nodes also have an iteration start property which specifies an offset into the series of iterations at which the animation node 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 section 3.10 Core animation node 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 node 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.10.2 Calculating the active duration

In order to calculate the active duration we first define the repeated duration as follows:

repeated duration = iteration duration × iteration count

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

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

The active duration is calculated according to the following steps:

1. If the playback rate is zero, return Infinity.
2. Otherwise, return repeated duration / abs(playback rate).

3.10.3 Transforming the local time

3.10.4 Calculating the current iteration

The current iteration can be calculated using the following steps:

1. If the scaled active time is null, return null.
2. If the scaled active time is zero, return zero.
3. If the iteration duration is zero, 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 infinite, the result of floor(scaled active time / iteration duration) will be zero as defined by IEEE 754-2008.

3.11.1 Calculating the directed time

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

1. If the iteration time is null, return null.
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 node 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.

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

   Otherwise, return the iteration duration - iteration time.

3.12.2 Timing functions

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

Animation nodes 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 node depends on the type of the animation node.

3.12.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 time fractions serve as x values of the curve, whilst the y values are the output time fractions.

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

The timing functions produced by each of the keyword values associated with cubic Bézier timing functions accepted by the AnimationTiming.easing 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 [CSS3-VALUES]):

<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.12.4 Timing in discrete steps

This section is non-normative.

It is possible to scale an animation node's timing so that the animation node 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 time fraction whilst the range represents the output time fraction 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 section 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 node or applied to an animation effect associated with an animation node, an additional before flag is passed. The value of the before flag is determined as follows:

1. If the active time of the animation node is null, the before flag is not set and these steps should be aborted.
2. Determine the current direction using the procedure defined in section 3.11.1 Calculating the directed time.
3. If either the current direction is forwards or the animation node playback rate ≥ 0 (but not when both conditions are true), let going forwards be true, otherwise it is false.
4. The before flag is set if the animation node is in the before phase and going forwards is true; or if the animation node 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.12.5 Calculating the transformed time

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

1. If the directed time is null, return null.
2. If the iteration duration is infinity, return the directed time.
3. Let iteration fraction be the result of evaluating directed time / iteration duration unless iteration duration is zero, in which case let iteration fraction be zero.
4. Let scaled fraction be the result of evaluating the animation node's timing function with iteration fraction as the input time fraction.
5. Return the result of evaluating scaled fraction × iteration duration. If the scaled fraction is zero, let the result be zero.

   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.13.2 The start time of children of an animation group

The start time of a child animation node of an animation group is zero.

Note that specific types of animation groups may override this definition to provide other kinds of synchronization behavior.

3.13.3 The intrinsic iteration duration of an animation group

The intrinsic iteration duration of an animation group is based on the time when the last child animation node completes its active interval and is calculated using the following procedure.

1. Define the end time of an animation node as :

   end time = start time + start delay + active duration + end delay

2. The intrinsic iteration duration depends on the number of child animation nodes as follows,

   If the group has no child animation nodes,

   the intrinsic iteration duration is zero.

   Otherwise,

   1. Let maximum end time be the maximum value after calculating the end time of each child animation node in the group.
   2. The intrinsic iteration duration is the result of evaluating max(0, maximum end time).

This definition of the intrinsic iteration duration may be overridden by specific types of animation groups.

3.13.4 Animation sequences

This section is non-normative.

Specific types of animation groups can be used to provide different kinds of synchronization behavior for their children. This specification defines one additional type of animation group: an animation sequence. Animation sequences arrange the start times of their children so that they run one at a time, in turn.

Compare the two arrangements illustrated below:

Animation groups and animation sequences.
(a) is a regular animation group where all the children run simultaneously.
(b) is an animation sequence where the children run in turn.

Since animation groups can also contain other animation groups, complex synchronization is possible by combining different types of groups as illustrated below.

An animation sequence that contains a regular animation group as a child.
The animation group waits for the previous child of the animation sequence to finish, and then the children of the animation group play simultaneously. After they have finished the next child of the animation sequence plays.

An animation sequence is a type of animation group that schedules its child animation nodes such that they play in turn following their order in the group. This sequencing is achieved by adjusting the start time of each child animation node in the group.

3.13.4.1 The start time of children of an animation sequence

The start time of a child animation node of an animation sequence is the end time of the child's previous sibling. If the child has no previous sibling the start time is zero.

When the active duration is positive infinity the behavior for calculating the end time of an animation node and the start time of subsequent children follows the usual behavior defined by IEEE 754-2008. As a result, if any of the children of an animation sequence has an infinite active duration, any children that occur later in the sequence will not play.

Similarly, the above definition does not restrict start times to positive values and hence some children may not play due to a negative start delay on children that occur earlier in the group since their active interval may end before the group's start time.

This section is non-normative.

Because the start of the active interval is based on the sum of an animation node's start time and start delay, the active intervals of children of an animation sequence need not run in strict sequence but can be shifted back and forth by using the start delay as shown in the following diagram.

Example of using the start delay on children of an animation sequence to shift their timing so that they overlap (a negative delay) or are spaced apart (a positive delay).

A negative start delay can be used to cause the active interval of two children to overlap. Note that the start delay affects the start time of subsequent children in the group.

3.14.1 Calculating the time fraction

Before passing the transformed time of an animation to its animation effect it is converted to a time fraction. The time fraction of an animation node is calculated according to the following steps:

If the iteration duration is zero,

the time fraction is as follows,

If local time < start delay,

Return the result of recalculating the transformed time using an iteration duration of 1.

Otherwise,

1. Let normalized active duration be the result of recalculating the active duration using an iteration duration of 1.
2. Return the result of recalculating the transformed time using a local time of start delay + normalized active duration and an iteration duration of 1.

Otherwise,

Return transformed time / iteration duration unless transformed time is null, in which case return null.

Since timing functions are allowed to produce output times outside the range [0, 1] it is possible that the value calculated for a time fraction also lies outside this range.

4.1.1 Target properties

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

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

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 4?

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.4 Intermediate animation values

Given a time fraction, a current iteration, and an underlying value, an animation effect produces an intermediate animation value for each animatable target property. The procedure for calculating this value depends on the specific type of animation effect and is defined subsequently (see section 4.3.2 The intermediate animation value of a keyframe animation effect and section 4.4.4 The intermediate animation value of a motion path animation effect).

Before being applied to the target properties, these intermediate animation values are composed together using the process defined in section 4.2 Combining animations.

4.2.1 The animation stack

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

The relative priority of any two animation effects, A and B, within an animation stack is established by comparing the properties of the animations applying A and B as follows:

1. Let the associated player of an animation effect be the player associated with the animation that is applying the animation effect to the property with which this animation stack is associated.
2. Sort A and B by applying the following conditions in turn until the order is resolved,
   1. Sort A and B using any custom player priority specified for the associated player of each of A and B so that lower priorities sort first.
   2. Sort by the player sequence number so that lower sequence numbers sort first.
   3. Sort A and B in tree order. (By this point, A and B must have the same player since otherwise the order would have been resolved in the previous step.)

Animation effects that sort earlier have lower priority.

4.2.2 Calculating the result of an animation stack

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

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

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

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

4.2.3 Animation composition

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

This specification defines three composite operations as follows:

replace

The result of compositing the intermediate animation value with the underlying value is simply the intermediate animation value.

add

The intermediate animation 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 + intermediate animation value.

accumulate

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

4.2.4 Applying the composited result

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

4.2.5 Animation accumulation

Similar to the compositing performed between intermediate animation values (see section 4.2.3 Animation composition), the iteration composite operation determines how values are combined between successive iterations of the same animation.

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 intermediate animation value for each type of animation effect.

4.3.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 animation 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(
  new KeyframeEffect([ { left: '0px' },
                       { left: '-20px' },
                       { left: '100px' },
                       { left: '50px' } ], { spacing: "paced" }), 1000);

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(
  new KeyframeEffect([ { left: '0px' },
                       { left: '-20px' },
                       { left: '100px', offset: 0.5 },
                       { left: '50px' } ], { spacing: "paced" }), 1000);

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 animation values from a keyframe animation effect, an absolute value must be computed for the keyframe offset of each keyframe with a null offset. The values computed depend on the keyframe spacing mode specified for the keyframe animation effect. The keyframe spacing modes are:

distribute

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

paced

Indicates that keyframes with a null keyframe offset null 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.

4.3.2 The intermediate animation value of a keyframe animation effect

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

1. Let target property be the property for which the intermediate animation 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 keyframe offset of 0, create a new keyframe with a 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 keyframe offset of 1, create a new keyframe with a 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 time fraction < 0 and there is more than one keyframe in property-specific keyframes with a keyframe offset of 0,

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

    If time fraction ≥ 1 and there is more than one keyframe in property-specific keyframes with a 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 keyframe offset is less than or equal to time fraction and less than 1. If there is no such keyframe (because, for example, the time fraction is negative), add the last keyframe whose 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 animation 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 animation 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 animation 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 keyframe offset of the first keyframe in interval endpoints.
14. Let end offset be the keyframe offset of last keyframe in interval endpoints.
15. Let interval distance be the result of evaluating (time fraction - 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 that 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 time fractions 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.4.1 Distance along a path

The procedure used for calculating the length of a path or a subsection is provided by the definition of distance along a path in SVG [SVG2].

4.4.2 Spacing motion paths

The following properties control the rate of progress of a motion path animation effect:

spacing mode

Specifies the strategy used for determining the offset of each spacing point or path command when not specified by a point offset. The possible spacing modes are identical to those defined for keyframe animation effects (see section 4.3.1 Spacing keyframes).

Note that a spacing mode of distribute has no effect if point offsets are specified. This is because spacing between point offsets always uses paced spacing mode.

spacing points

An optional sequence of real numbers in the range [0.0, 1.0] that correspond to fractions of the total path length. The animation effect produces animation values such that the animation target moves backwards and forwards along the motion path following the sequence indicated by these points.

Furthermore, the point on the motion path indicated by each such number forms a handle that may be associated with a point offset or positioned by the spacing mode.

point offsets

An optional ordered sequence of real numbers in the range [0.0, 1.0] that specifies the time fraction when the corresponding spacing point, or, if spacing points are not provided, drawing path command, should be visited.

If specified, the first value in the sequence must be 0.0 and the last value must be 1.0. There must be as many items in the sequence of point offsets as in the sequence of spacing points, if provided. If a sequence of spacing points is not provided, the number of items in point offsets must equal the number of drawing path commands in the motion path plus one.

point easing

An optional ordered sequence of timing functions that specify the easing behavior between each pair of spacing points, or, if spacing points are not provided, between each pair of drawing path commands.

If specified, there must be as many items as in the sequence of spacing points minus one, if provided. If a sequence of spacing points is not provided, the number of items in point easing must equal the number of drawing path commands in the motion path.

4.4.3 Determining the path fraction

The path fraction for a given time fraction, progress, is determined using the following procedure:

1. If effective point offsets is empty, let path fraction equal time fraction and abort these steps.
2. If effective point offsets has only one item, let path fraction equal the value of the one item in effective spacing points and abort these steps.
   Effective point offsets can only have one item if spacing points has exactly one item. In this case, the effective points offsets will always be a list containing just the value 0.
3. If progress ≥ 1, let the path fraction equal the value of the last item in effective point offsets and abort these steps.
4. If progress < 0, let the path fraction equal the value of the first item in effective point offsets and abort these steps.
5. Let start index and end index represent the zero-based indices of the last pair of successive values in effective point offsets such that start offset ≤ progress ≤ end offset.
6. Let interval fraction be the ratio of the difference between progress and the offset at start index, and the difference between the offset at end index and the offset at start index.
7. Let scaled interval fraction be the result of applying the timing function from effective point easing at index start index with interval fraction as the input.
8. Let segment start and segment end be the values in effective spacing points at the indicies start index and end index respectively.
9. Let the path fraction be the result of evaluating the following formula: scaled interval fraction * (segment end - segment start) + segment start.

4.4.4 The intermediate animation value of a motion path animation effect

The intermediate animation value of a motion path animation effect for a given time fraction, current iteration, and underlying value is given by the following process:

1. Let distance be the path fraction for the given time fraction.
2. Let displacement be the point located distance along the motion path using the definition for distance along a path.

   If distance indicates a point on the path that is coincidental with one or more orientation path commands, displacement is the point after all orientation path commands (this will be the start of the next drawing path command if there is one).

3. Let the translation component be the translation transform required to transform the point at the start of motion path to displacement.
4. Calculate the rotation component according to the first match condition from the following:

   If the automatic rotation flag is set,

   the rotation component is a transform representing the sum of:

   • the angle of the tangent vector at displacement, and
   • the rotation angle.

   Otherwise,

   the rotation component is a transform representing the rotation angle.

   When calculating the angle of the tangent vector, if there are no drawing path commands in the motion path, the the angle should be taken to be zero.

   The original text for this section contained the following qualifications but I'm not sure how meaningful they are:

   • For continuous path commands (all elements except moveto), the angle of the tangent vector for the purpose of these calculations is defined to be an integer multiple of 2π different from the value given by standard mathematical formulae for tangents to curves in 2 dimensional space.
   • For moveto path commands, which are discontinuous, the angle of the tangent vector for the purpose of these calculations is always an integer multiple of 2π.
   • The initial value of the angle of the tangent vector is computed using the first element of the curve, and is always in the range [0, 2π).
   • Single continuous path commands must never produce tangent vector angles that are discontinuous over their defined region. This implies that a single unique solution is available for all points on continuous path commands.
   • When computing angles after discontinuous or non-smooth jumps, multiple possible solutions may be available. These solutions will differ by integer multiples of 2π. In such cases the solution that lies closest to the previous tangent angle is used.
5. Let the transform value be the result of by constructing a transform list consisting of the translation component followed by the rotation component.
   What's the value in keeping these separate? Shouldn't we collapse them?
6. Let the unaccumulated value be the result of combining the underlying value (V_a) with the transform value (V_b) using the composite operation of the effect.
7. Let the intermediate animation value be unaccumulated value.
8. If the iteration composite operation of this motion path animation effect is accumulate, perform the following steps:
   1. Let the final transform value be the value calculated for the transform value when performing the first five steps of this procedure using a time fraction of 1.
   2. Perform the following step current iteration times:
      • Set the intermediate animation value to the result of combining the current value of intermediate animation value (V_a) with final transform value (V_b) using the accumulation procedure defined by the animatable as transform list animation behavior.
9. Return the intermediate animation value.

4.5.1 Sampling custom effects

Custom effects are called for each referencing animation when a sample is performed based on the following criteria.

1. If, on the previous sample, the animation referencing the custom effect:
   • was in effect, and
   • referenced this same custom effect, and
   • had a different animation target

   Call the callback passing a null time fraction and the animation target from the previous sample as parameters to the callback.

2. Call the callback for the current animation target based on the first matching condition from the following:

   If the animation referencing the custom effect is not in effect but was in effect in the previous sample,

   Call the callback passing a null time fraction and the current animation target as parameters to the callback.

   Otherwise, if the animation referencing the custom effect:

   • is in effect, and
   • was not in effect in the previous sample, or was in effect but with a different time fraction or current iteration,

   Call the callback passing with the referencing animation's current time fraction and animation target as parameters to the callback.

4.5.2 Execution order of custom effects

Since custom effects, unlike animation effects, are not limited to a single target property, the steps for assessing their order of execution differs from animation effects.

Custom effects are executed after all animation effects have completed and applied their result to their targets (see section 4.2.4 Applying the composited result).

Need to define this more precisely. Are styles flushed? Presumably they are. Can we suspend reflow for the duration of executing the script-based animation effects and just do it once afterwards?

Within the set of custom effects, the order of execution is the same as that defined for animation effects in section 4.2.1 The animation stack. Items sorted earlier are executed before those sorted later.

5.1.1 Attributes

currentTime of type double, readonly, nullable

Returns the time value for this timeline or null if this timeline is not started.

5.1.2 Methods

play

Creates a new AnimationPlayer object associated with this timeline that is scheduled to start at currentTime.

The timeline attribute of the newly-created AnimationPlayer object will be set to this object.

Similarly, the start time of the newly created player will be set to the value of this object's currentTime attribute at the moment the method was called.

The setting of the source attribute is described below under the description of the source parameter.

The currentTime attribute of the AnimationPlayer object is a calculated value described in section 3.5.1 The current time of a player.

The playbackRate and paused attributes take on their default values as described in the definitions of the playback rate and paused state properties of player objects.

Parameter	Type	Nullable	Optional	Description
source	AnimationNode	✔	✔ (null)	The source content to assign to the newly-created AnimationPlayer object. The source attribute of the created AnimationPlayer is set by following the procedure defined for updating that attribute. As a result, if source is already associated with a player, it will be disassociated first before being associated with the new AnimationPlayer.

Return type: AnimationPlayer

getAnimationPlayers

Returns the set of AnimationPlayer objects associated with this timeline that have associated source content which is current.

The returned list is sorted in increasing order by player sequence number.

No parameters.

Return type: sequence<AnimationPlayer>

5.2.1 Attributes

source of type AnimationNode, nullable

The source content associated with this player.

A player can only be associated with at most one animation node, and likewise, an animation node can only be associated with at most one player. In order to maintain these invariants, on setting this value, the following procedure is performed:

1. Let old value be the current value of the source attribute.
2. Let new value be the value to set.
3. If new value is the same object as old value, return.
4. If old value is not null, disassociate old value from this player.
5. If new value is not null, perform the steps associated with the first matching condition of the following:

   If new value has no parent group and is associated with a player,

   disassociate new value from its player.

   If new value has a parent group,

   remove new value from its parent group by calling new value.remove().

   Otherwise,

   do nothing.

6. Associate new value with this player.
7. Set the source attribute to new value.

timeline of type AnimationTimeline, readonly

The timeline associated with this player.

startTime of type double

Returns the start time of this player. Setting this attribute updates the player start time using the procedure defined in section 3.5.2.6 Updating the player start time.

currentTime of type double

The effective current time of this player. Setting this attribute follows the procedure defined in section 3.5.2.9 Performing a seek.

playbackRate of type double

The playback rate of this player. Setting this attribute follows the procedure defined in section 3.5.3.1 Updating the playback rate.

paused of type boolean, readonly

The paused state of this player.

finished of type boolean, readonly

Returns true if this player has reached or passed the end of its source content in its current playback direction. This corresponds to when the player is limited.

onfinish of type EventHandler

The event handler for the finish event.

Note that the EventHandler callback interface type is defined in [HTML5].

5.2.2 Methods

cancel

Set source to null and clears all effects associated with the previous source content.

We need to make sure, for example, that any custom effects get called with a null sample time so they can remove their effects. This applies to manually setting source to null as well so we should define this behavior there.

No parameters.

Return type: void

finish

Seeks the player to the end of the source content in the current direction as follows:

If player playback rate < zero,

Seek the player so its current time is zero.

If player playback rate equals zero,

Do nothing.

If player playback rate > zero,

Seek the player so its current time is equal to the end time of the source content or zero if there is no source content associated with this player..

Exceptions:

DOMException of type InvalidStateError

Raised if the end time of this player's source content is infinity and the player playback rate is > zero.

No parameters.

Return type: void

play

Unpauses the player and rewinds if it has finished playing using the following procedure:

1. Set the paused state of the player to false using the procedure defined in section 3.5.2.8 Updating the paused state.
2. If source content is associated with the player, adjust the current time of the player as follows:

   If player playback rate > 0; and either current time < zero or current time ≥ source content's end time,

   Seek to time zero.

   If player playback rate < 0; and either current time ≤ zero or current time > source content's end time,

   Seek to the source content's end time.

   Otherwise,

   Do nothing.

3. Set the player's finished flag to false.

No parameters.

Return type: void

pause

Set the paused state of this player to true using the procedure defined in section 3.5.2.8 Updating the paused state.

No parameters.

Return type: void

reverse

Inverts the playback rate of this player and seeks to the start of the source media if it has finished playing in the reversed direction using the following procedure.

1. If the player playback rate is zero, abort these steps.
2. If source content is associated with the player, adjust the current time of the player as follows:

   If player playback rate > zero and effective current time > source content's end time,

   Seek to the source content's end time.

   If player playback rate < zero and effective current time < zero,

   Seek to time zero.

   Otherwise,

   Do nothing.

3. Set the player playback rate to -player playback rate following the steps in section 3.5.3.1 Updating the playback rate.
4. Set the paused state of the player to false.

   Is this unpausing behavior correct?

Note that unlike play(), the player's finished flag is not explicitly reset here since that behavior is performed by the procedure for updating the player playback rate defined in section 3.5.3.1 Updating the playback rate.

No parameters.

Return type: void

5.3.1 Attributes

localTime of type double, readonly, nullable

The local time of this animation node.

localTime will be null if this animation node is not associated with a player or if it has a parent animation group that is not in effect.

currentIteration of type unsigned long, readonly, nullable

The current iteration index beginning with zero for the first iteration.

timing of type AnimationTiming, readonly

Returns the input timing properties specified for this animation node. This is comparable to the specified style on an Element, elem.style.

Should we make this writeable? Then you could do:

animA.timing = animB.timing;

Doing so would probably also involve defining AnimationTiming.clone and a constructor for AnimationTiming.

Representing these parameters has been a particularly contentious topic.

The current arrangement:

• requires defining both an AnimationTiming interface and an AnimationTimingInput dictionary type which increases the API surface area somewhat
• means that setting the value occurs at a different place (anim.timing.duration) to reading the value (typically, anim.duration)
• opens up questions about whether AnimationTiming objects should be share-able or not
• uses a union of a string and a double to represent a duration which opens up questions about whether strings such as "3s" should be allowed (and allowing them makes walking the tree more complex).

However, it separates "specified" timing from "computed" timing which some consider advantageous.

The only situation where calculated values and input values differ is for duration.

One alternative that has been proposed is to introduce a Duration interface as follows:

interface AnimationNode {
   // AnimationTiming
   attribute double   delay;
   attribute FillMode fill;
   attribute Duration duration;
   attribute double   playbackRate;
   // ...
   
   // Scheduled time
   readonly attribute double              startTime;
   readonly attribute unrestricted double endTime;
};

interface Duration {
  double    ms;
  DOMString string;
}

Usage is as follows:

var specifiedDur  = anim.duration.string; // "auto"
var calculatedDur = anim.duration.ms; // 5000

// Update duration to 3s
anim.duration.ms = 3000;
// anim.duration.string -> "3s"

// Update duration to 3s (alt.)
anim.duration.string = "3s";
// anim.duration.ms -> 3000

// Reset to auto
anim.duration.string = "auto";  
// anim.duration.ms -> 5000

Your feedback is most welcome at public-fx@w3.org, subject [web-animations] ….

startTime of type double, readonly

The start time of this animation node in milliseconds. This is the time at which the parent animation group, if any, has scheduled this child to run within its transformed time space, that is, the animation node's inherited time space.

The start of the active interval is based on the sum of the start time and start delay.

duration of type unrestricted double, readonly

The iteration duration of this animation node.

Unlike the duration attribute of the AnimationTiming interface or AnimationTimingInput dictionary, this attribute returns the calculated value of the iteration duration. If timing.duration is the string auto or any unsupported value, this attribute will return the current calculated value of the intrinsic iteration duration.

This value may be changed by setting the duration attribute of the timing member of this interface.

activeDuration of type unrestricted double, readonly

The active duration of this animation node.

endTime of type unrestricted double, readonly

The end time of the animation node expressed in milliseconds in inherited time space. This corresponds to the end of the animation node's active interval plus any end delay.

parent of type AnimationGroup, readonly, nullable

The parent animation group of this animation node or null if this animation node does not have a parent animation group.

Should this be parentGroup?

previousSibling of type AnimationNode, readonly, nullable

The previous sibling of this animation node.

nextSibling of type AnimationNode, readonly, nullable

The next sibling of this animation node.

player of type AnimationPlayer, readonly, nullable

The player with which this animation node is associated, if any. This object can be used to perform play control such as pausing or rewinding on this animation node and all other animation nodes in the same hierarchy.

This will be null if this animation node is not associated with a player.

Feedback has been provided that suggests this reference causes the relationship between AnimationPlayers and AnimationNodes to be circular, which confuses the model. The player attribute should be considered at risk unless a strong use case for the reference arises.

5.3.2 Methods

before

Inserts nodes before this animation node.

1. If there is no parent animation group, terminate these steps.
2. If any of the animation nodes in nodes is an inclusive ancestor of this animation node throw a HierarchyRequestError exception and terminate these steps.
3. Insert nodes before this animation node.

Note that this definition precludes the following usage since node is an inclusive ancestor of itself:

node.before(node); // throws HierarchyRequestError

Parameter	Type	Nullable	Optional	Description
nodes	AnimationNode...	✘	✘

Return type: void

after

Inserts nodes after this animation node.

1. If there is no parent animation group, terminate these steps.
2. If any of the animation nodes in nodes is an inclusive ancestor of this animation node throw a HierarchyRequestError exception and terminate these steps.
3. Let reference child be the next sibling of this animation node not in nodes.
4. Insert nodes before reference child.

Parameter	Type	Nullable	Optional	Description
nodes	AnimationNode...	✘	✘

Return type: void

replace

Replaces this AnimationNode with the passed in nodes.

1. If there is no parent animation group, terminate these steps.
2. If any of the animation nodes in nodes is an inclusive ancestor of the parent animation group throw a HierarchyRequestError exception and terminate these steps.
3. Let reference child be the next sibling of this animation node not in nodes.
4. Remove this animation node from its parent animation group.
5. Insert nodes before reference child.

Parameter	Type	Nullable	Optional	Description
nodes	AnimationNode...	✘	✘

Return type: void

remove

Removes this animation node from its parent animation group or player.

No parameters.

Return type: void

5.4.1 Attributes

delay of type double

The start delay which represents the number of milliseconds from an animation node's start time to the start of the active interval.

Now that we have endDelay, should we change this back to startDelay?

endDelay of type double

The end delay which represents the number of milliseconds from the end of an animation node's active interval until the start time of any animation node that may follow, for example, in an animation sequence.

fill of type FillMode

The fill mode as specified by one of the FillMode enumeration values.

When performing timing calculations the special value auto is expanded to one of the fill modes recognized by the timing model as follows,

If the animation node to which the fill mode is being is applied is an animation,

Use none as the fill mode.

Otherwise,

Use both as the fill mode.

iterationStart of type double

The animation node's iteration start property.

A finite real number greater than or equal to zero representing the number of iterations into the animation node at which to begin. For example, a value of 0.5 would cause the animation node to begin half-way through the first iteration.

Values less than zero are clamped to zero for the purpose of timing model calculations.

Note that the value of iterations is effectively added to the iterationStart such that an animation node with an iterationStart of ‘0.5’ and iterations of ‘2’ would still repeat twice however it would begin and end half-way through the animation node's iteration interval.

Setting the iterationStart to a value greater than or equal to one is typically only useful in combination with an animation effect that has an iteration composite operation of ‘accumulate’.

iterations of type unrestricted double

The animation node's iteration count property.

A real number greater than or equal to zero (including positive infinity) representing the number of times to repeat the animation node.

Values less than zero and NaN values are treated as the value 1.0 for the purpose of timing model calculations.

duration of type (unrestricted double or DOMString)

The iteration duration which is a real number greater than or equal to zero (including positive infinity) representing the time taken to complete a single iteration of the animation node.

The string value auto is used to indicate that the iteration duration reflects the animation node's intrinsic iteration duration.

Real numbers less than zero, NaN values, and strings other than the lowercase value auto are treated the same as auto for the purpose of timing model calculations.

Should we allow strings such as "3s" here? i.e. a CSS <time>. It might be useful for readability but introduces complexity when handling this member (need to test the type, then possibly parse the string). It also introduces the issue of whether we should parse a full clock value.

playbackRate of type double

The animation node's playback rate property.

This is a multiplier applied to the local time potentially causing the node to run at a different rate to its natural speed.

direction of type PlaybackDirection

The playback direction of the animation node as specified by one of the PlaybackDirection enumeration values.

easing of type DOMString

The timing function used to scale the time to produce easing effects.

The syntax of the string is defined by the following production:

"linear" | <cubic-bezier-timing-function> | <step-timing-function>

Unrecognized string values or values that correspond to a timing function that is not supported for the type of animation node to which this property is applied are treated as if the linear keyword was specified for the purpose of timing model calculations.

In future we may extend this so that it is possible to query the individual functions in the string. It may be possible to do this by extending this attribute using some stringifier magic, or else we could just add easingList similar to HTML's classList.

5.5.1 Dictionary AnimationTimingInput Members

delay of type double, defaulting to 0

The specified start delay.

See the description of the delay attribute on the AnimationTiming interface.

endDelay of type double, defaulting to 0

The specified end delay.

See the description of the endDelay attribute on the AnimationTiming interface.

fill of type FillMode, defaulting to "auto"

The fill mode as specified by one of the FillMode enumeration values.

iterationStart of type double, defaulting to 0.0

The animation node's iteration start property.

See the description of the iterationStart attribute on the AnimationTiming interface.

iterations of type unrestricted double, defaulting to 1.0

The animation node's iteration count property.

See the description of the iterations attribute on the AnimationTiming interface.

duration of type (unrestricted double or DOMString), defaulting to "auto"

The iteration duration of the animation node.

See the description of the duration attribute on the AnimationTiming interface.

playbackRate of type double, defaulting to 1.0

The animation node's playback rate property.

See the description of the playbackRate attribute on the AnimationTiming interface.

direction of type PlaybackDirection, defaulting to "normal"

The playback direction of the animation node.

See the description of the direction attribute on the AnimationTiming interface.

easing of type DOMString, defaulting to "linear"

The timing function used to scale the time to produce easing effects.

See the description of the easing attribute on the AnimationTiming interface.

5.5.2 The FillMode enumeration

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

5.5.3 The PlaybackDirection enumeration

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

5.6.1 Constructors

AnimationGroup

Creates a new AnimationGroup object using the following procedure:

1. Create a new AnimationGroup object, group.
2. Set timing input as follows,

   If timing is an AnimationTimingInput object,

   Let timing input refer to timing.

   If timing is a double,

   Let timing input be a new AnimationTimingInput object with all members set to their default values and duration set to timing.

   Otherwise (timing is undefined),

   Let timing input be a new AnimationTimingInput object with all members set to their default values.

3. Set group.timing to a new AnimationTiming object whose attributes are assigned the value of the member of the same name on timing input.

   The above two steps are identical with the constructor for Animation and should be factored out somewhere.

4. Insert children before null.

Note that since AnimationTiming objects have the same member names as AnimationTimingInput dictionaries, it is also possible to pass the timing member of another AnimationNode as the timing parameter.

Doing so will cause the AnimationTiming object to be treated as an AnimationTimingInput dictionary and thus it will effectively be cloned, not shared.

Parameter	Type	Nullable	Optional	Description
children	sequence<AnimationNode>	✔	✘	A sequence of animation nodes to add as children of this group. These children are appended in sequence using the same semantics as the AnimationGroup.append method.
timing	(unrestricted double or AnimationTimingInput)	✘	✔	The timing properties or iteration duration of the new animation group.

5.6.2 Attributes

children of type AnimationNodeList, readonly

The list of child animation nodes in the group.

firstChild of type AnimationNode, readonly, nullable

The first child of this animation group.

lastChild of type AnimationNode, readonly, nullable

The last child of this animation group.

5.6.3 Methods

prepend

1. If any of the animation nodes in nodes is an inclusive ancestor of this animation node throw a HierarchyRequestError exception and terminate these steps.
2. Insert nodes before the first child.

Parameter	Type	Nullable	Optional	Description
nodes	AnimationNode...	✘	✘

Return type: void

append

1. If any of the animation nodes in nodes is an inclusive ancestor of this animation node throw a HierarchyRequestError exception and terminate these steps.
2. Insert nodes before null.

Parameter	Type	Nullable	Optional	Description
nodes	AnimationNode...	✘	✘

Return type: void

clone

Creates a deep copy of this AnimationGroup object using the following procedure.

1. Let source be this AnimationGroup object, the object to be cloned.
2. Let cloned timing be a new AnimationTimingInput object whose members are assigned the value of the attribute with the same name on source.timing.
3. Let cloned children be an empty sequence of AnimationNode objects.
4. For each child in source.children, append the result of calling child.clone() to cloned children.
5. Return a new AnimationGroup object created by calling the AnimationGroup constructor with parameters AnimationGroup(cloned children, cloned timing).

No parameters.

Return type: AnimationGroup

5.6.4 Definitions for manipulating hierarchies

The next sibling of node not included in a set of animation nodes, nodes is determined using the following steps:

1. Let context node be node.
2. While the next sibling of context node is not null perform the following steps:
   1. Let context node be the next sibling of context node.
   2. If context node is not in nodes return context node and terminate these steps.
3. Return null.

To remove a node from its parent animation group or player, perform the steps corresponding to the first matching condition from below, if any:

If node has a parent animation group,

Remove node from the parent animation group's list of child animation nodes.

If node is directly associated with a player,

Disassociate node from the player.

To insert a series of zero or more animation nodes, nodes, to parent's list of child animation nodes before reference child perform the following steps for each node in nodes:

1. Remove node from its parent.
2. Insert node to parent's list of child animation nodes before reference child.

5.7.1 Attributes

length of type unsigned long, readonly

The number of animation nodes in the list.

5.7.2 Methods

item [index]

Returns the animation node at index. If index is greater than or equal to length returns null.

Parameter	Type	Nullable	Optional	Description
index	unsigned long	✘	✘

Return type: AnimationNode, nullable

5.8.1 Constructors

AnimationSequence

The meaning and handling of each of the parameters in this constructor is identical to the constructor for AnimationGroup.

Parameter	Type	Nullable	Optional	Description
children	sequence<AnimationNode>	✔	✘
timing	(unrestricted double or AnimationTimingInput)	✘	✔

5.8.2 Methods

clone

Creates a deep copy of this AnimationSequence object using the same procedure as defined for AnimationGroup.clone except that a new AnimationSequence object is created.

No parameters.

Return type: AnimationSequence

5.9.1 Constructors

Animation

Creates a new Animation object using the following procedure:

1. Create a new Animation object, animation.
2. Set timing input as follows,

   If timing is an AnimationTimingInput object,

   Let timing input refer to timing.

   If timing is a double,

   Let timing input be a new AnimationTimingInput object with all members set to their default values and duration set to timing.

   Otherwise (timing is undefined),

   Let timing input be a new AnimationTimingInput object with all members set to their default values.

3. Set animation.timing to a new AnimationTiming object whose attributes are assigned the value of the member of the same name on timing input.
4. Set animation.effect to the result of applying the procedure for converting an effect to an IDL value to effect.

Examples of the usage of this constructor are given in section 5.9.5 Creating a new Animation object.

Note that as with the constructor for AnimationGroups it is possible to pass in an AnimationTiming object here (e.g. the timing member of another AnimationNode) in which case it will be cloned.

Parameter	Type	Nullable	Optional	Description
target	Animatable	✔	✘	The animation target or target pseudo-element. This may be null for animations that do not target a specific element.
effect	object	✔	✘	The animation effect used to set the effect attribute of the newly-created Animation object. The processing of this parameter is defined normatively in section 5.9.4 Processing the effect parameter. Following is a non-normative summary of this handing. effect may be one of the following: An AnimationEffect object, An EffectCallback function, A single Keyframe object, A sequence of Keyframe objects, or null If this parameter is an AnimationEffect object or EffectCallback object, it will be shared with any other Animation objects referring to the same AnimationEffect or EffectCallback object. It will not be copied. If this parameter is of type Keyframe or sequence<Keyframe>, the animation effect of the newly-created Animation will be a newly-created KeyframeEffect object initialized by using this object as the list of keyframes and with all other parameters set to their default values. If this parameter is null, the newly-created Animation will also have a null animation effect.
timing	(unrestricted double or AnimationTimingInput)	✘	✔	The timing properties or iteration duration of the new animation.

5.9.2 Attributes

effect of type (AnimationEffect or EffectCallback), nullable

The animation effect or custom effect to apply. May be null in which case the animation will produce no observable effect.

On setting, if the previous value was an EffectCallback, we should call the old callback with a null time fraction so it can clear its result.

target of type Animatable, nullable

The element or pseudo-element being animated by this object. This may be null for animations that do not target a specific element such as an animation that produces a sound using an audio API.

5.9.3 Methods

clone

Creates a copy of this Animation object using the following procedure.

1. Let source be the Animation object to clone, that is, this object.
2. Let cloned timing be a new AnimationTimingInput object whose members are assigned the value of the attribute with the same name on source.timing.
3. The AnimationEffect is cloned depending on the type of source.effect as follows,

   If source.effect is an Animation object,

   Let cloned effect be the result of calling source.effect.clone().

   If source.effect is an EffectCallback object,

   Let cloned effect be source.effect.

   Otherwise,

   Let cloned effect be null.

4. Return a new Animation object created by calling the Animation constructor with parameters Animation(source.target, cloned effect, cloned timing).

No parameters.

Return type: Animation

5.9.4 Processing the effect parameter

The effect parameter, an ECMAScript value passed to the Animation constructor or to the animate operation of the Animatable interface, may specify an EffectCallback, an AnimationEffect, a Keyframe a sequence of Keyframes, or null. However, since callback functions and dictionaries are not distinguishable in WebIDL, we define the processing of this parameter for ECMAScript here in prose.

The procedure for converting an effect to an IDL value with parameter effect is as follows:

If effect is null,

Return null.

If effect is a platform object that implements AnimationEffect,

return the IDL value that is a reference to the that platform object.

If IsCallable(effect) is true,

Return the result of applying the procedure for converting an ECMAScript value to an IDL callback function type to effect using EffectCallback as the callback function type.

Otherwise,

Return a new KeyframeEffect object constructed passing effect as the frames parameter.

Note that since the processing of this parameter is defined in prose, the above steps will take place after any coercion is applied to other parameters passed to the same operation.

5.10.1 Methods

animate

Creates a new Animation object whose animation target is the object on which the method is called, and calls the play method of the AnimationTimeline object of the document timeline of the node document [DOM4] of the element passing the newly created Animation as the argument to the method.

The following code fragment:

var anim = elem.animate({ opacity: 0 }, 2000);

is equivalent to:

var anim = new Animation(elem, { opacity: 0 }, 2000);
elem.ownerDocument.timeline.play(anim);

Returns the AnimationPlayer object returned by the play method of the AnimationTimeline.

Parameter	Type	Nullable	Optional	Description
effect	object	✔	✘	The effect to apply. This value is passed to the Animation constructor as the effect parameter and has the same interpretation as defined for that constructor.
timing	(double or AnimationTimingInput)	✘	✔	The timing parameters of the animation. This value is passed to the Animation constructor as the timing parameter and has the same interpretation as defined for that constructor.

Return type: AnimationPlayer

getCurrentAnimations

Returns the set of current Animation objects that have an animation effect whose animation target is this object.

The returned list of Animation objects is sorted by their associated animation effect using the procedure defined for sorting animation effects in section 4.2.1 The animation stack.

Note that the definition of a current animation does not include those animations whose local time falls after the active interval but which are still in effect due to a fill mode. As a result such animations are not returned by this method.

This is because in order to return such animations, user agents would be required to maintain all animations with a forwards fill indefinitely. As a result the resources consumed by an animated document would steadily accumulate over time.

Note that when called on Element objects, the list of returned Animations will not include those animations whose target is a PseudoElement associated with the Element since PseudoElement and Element are treated as independent Animatable objects.

Feedback has been provided that suggests direct references from AnimationNode objects to AnimationPlayers generate circular reference and confuse the model. Without this reference, getCurrentAnimations is not very useful, as the returned AnimationNodes can't be used to effect play control. In the absence of a strong use case for a reference from AnimationNode to AnimationPlayer, this feature should be considered at risk.

No parameters.

Return type: sequence<Animation>

getAnimationPlayers

Returns the set of AnimationPlayer objects whose source content is current and contains at least one animation whose animation target is this object.

If this object is the animation target of two or more animations which are associated with the same player, the corresponding AnimationPlayer object will still only appear in the returned list once.

The returned list is sorted in increasing order by player sequence number.

No parameters.

Return type: sequence<AnimationPlayer>

5.11.1 Attributes

iterationComposite of type IterationCompositeOperation

The iteration composite operation property of this animation effect as specified by one of the IterationCompositeOperation enumeration values.

composite of type CompositeOperation

The composite operation used to composite this animation effect with the animation stack, as specified by one of the CompositeOperation enumeration values.

5.11.2 Methods

clone

Creates and returns a new object of the same type as this object's most-derived interface such that it will produce the same output as this object.

We either need a more rigorous definition here or (probably better) a sets of steps on a per-subclass basis.

No parameters.

Return type: AnimationEffect

5.12.1 Values

replace

Corresponds to the replace iteration composite operation value such that the intermediate animation value produced is independent of the current iteration.

accumulate

Corresponds to the accumulate iteration composite operation value such that subsequent iterations of an animation build on the final value of the previous iteration.

5.13.1 Values

replace

Corresponds to the replace composite operation value such that the animation effect overrides the underlying value it is combined with.

add

Corresponds to the add composite operation value such that the animation effect is added to the underlying value with which it is combined.

accumulate

Corresponds to the accumulate composite operation value such that the animation effect is accumulated on to the underlying value.