Web Animations 1.0

3.4.1 The document timeline

Each document has a timeline called the document timeline whose time value at a given moment is calculated as a fixed offset from the global clock such that its zero time corresponds to the moment immediately prior to dispatching the load event of the document. Prior to this moment, the document timeline is not started.

For documents that support the concept of current document readiness, this is the moment after the current document readiness has changed to "complete" but before dispatching the load event. For user agents that support Navigation Timing [NAVIGATION-TIMING], this occurs between the domComplete and loadEventStart timings.

Since the document timeline is tied to the global clock by a fixed offset, time values reported by the document timeline increase monotonically. Furthermore, since no scaling is applied, these time values are proportional to wall-clock seconds.

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 - time drift

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.
• time drift is the time drift value described in section 3.5.2 Seeking and pausing.

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

It is often useful to treat the current time as zero when it would otherwise be null. We define the effective current time as being equal to current time unless the current time is null, in which case the effective current time is zero.

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

3.5.2 Seeking and pausing

Seeking and pausing 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 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 timed items.

However, in Web Animations, the start time of a player has special significance in determining the priority of animations (see section 4.2 Combining animations) and so we cannot simply adjust the start time. Instead, an additional offset is introduced called the time drift that further offsets a player's current time from its timeline. The effect of the time drift when seeking is illustrated below.

At time t, a seek is performed on the player changing its current time from 1.5s to 2s.
As a result, the time drift is set to -0.5s.
Note that the start time indicated by a red star does not change.

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 effectively causes the current time of a player to be offset from its timeline by means of setting the time drift.

The effect of pausing on a player's time drift is illustrated below.

The effect of pausing a player.
Whether pausing before or after a player's start time the duration of the interval during which the player was paused is added to the player's time drift whilst the start time remains unaffected.

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.6.1 The active interval

This section is non-normative.

The period that a timed item is scheduled to run is called its active interval. Each timed item has only one such interval.

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

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) A timed item with no delay; the start time and beginning of the active interval are coincident.
(b) A timed item with a positive delay; the beginning of the active interval is deferred by the delay.
(c) A timed item with a negative delay; the beginning of the active interval is brought forward by the delay.

Timed items define an active interval which is the period of time during which the item 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 timed item's start time and start delay

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

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

The lower bound of the active interval of a timed item, 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.2 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.

3.6.2 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. Timing 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 timed items 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 timed item (a) which has a start time of 1, the local time is 1.5.
For timed item (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 a timed item's start time only, and not on its start delay.

For a timed item, the inherited time at a given moment is based on the first matching condition from the following:

If the timed item has a parent timing group,

the inherited time is the parent timing group's current transformed time value.

If the timed item 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 a timed item is the timed item's inherited time minus its start time. If the inherited time is null then the local time is also null.

3.6.3 Timed item states

This section is non-normative.

At given moment, a timed item may 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 such as event dispatch.

The different states are illustrated below.

An example of the different states used for describing a timed item at a given time. Note that a timed item is considered to be in effect for all times inside the active interval as well as times outside the active interval where a fill mode is applied.

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

scheduled

The timed item's local time falls before the item's active interval. This state is only used in conjunction with the active state to define the current state.

active

The timed item's local time falls inside the item's active interval. Transitions to and from the active state trigger timing events as defined in section 5. Timing events.

current

The timed item's local time falls either before or inside the item's active interval, or the local time of an ancestor timing group falls before or inside its active interval thereby opening up the possibility that this timed item 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, in the absence of dynamic changes to the model, an implementation can safely discard all timed items that are not current and not referenced elsewhere provided they take care to preserve any fill values since they will not have any dynamic effect.

in effect

The timed item's local time falls either inside the item's active interval or outside the interval but at a time where the item's fill mode (see section 3.7 Fill behavior) causes it to affect its target. Timed items only produce a transformed time when the item is in effect. At all other times, the transformed time of a timed item is null.

The normative definition of each of these states follows.

A timed item is scheduled if either of the following conditions is true:

1. the timed item's local time is not null and is less than the item's startDelay, or
2. the timed item has a parent timing group which is a scheduled timed item.

A timed item is active if all of the following conditions are met:

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

A timed item is current if it is either scheduled or active or it has a parent timing group and the parent timing group is current.

A timed item 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 a timed item 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, a timed item 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 a timed item is simply its intrinsic iteration duration.

The intrinsic iteration duration of a timed item is zero, however some specific types of timed item such as timing groups override this behavior and provide an alternative intrinsic duration (see section 3.13.3.2 The intrinsic iteration duration of a parallel timing group and section 3.13.4.2 The intrinsic iteration duration of a sequence timing group).

The iteration duration of a timed item 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 timed item to complete.

Active duration

The time taken for the entire timed item 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 a timed item 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 a timed item 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 timed item repeats indefinitely.

In addition to the iteration count, timed items also have an iteration start property which specifies an offset into the series of iterations at which the timed item 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 timed item 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 timed item 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 accumulation operation property of sum.

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

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 floor(iteration start + iteration count).
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 item 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).

Timed items have one timing function associated with them. The default timing function is the linear timing function whose output is identical to its input.

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 Timing.timingFunction member from the script 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].

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

3.12.4 Timing in discrete steps

This section is non-normative.

It is possible to scale a timed item's timing so that the timed item 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 Animation's model for 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).

3.12.5 Paced timing

A paced timing function scales the input time such that the resulting time values cause a referenced property that is animated by a specified animation effect, referred to as the paced effect, to change at a constant rate over the period of time for which the paced timing function applies.

The syntax for specifying a paced timing function is: paced(<property>). The <property> argument is the referenced property of the paced timing function.

The paced effect is the animation effect specified on the same timed item where the paced timing function is applied. As a result, paced timing functions can only be used on animations and not other types of timed items.

If any of the following conditions is true, the linear timing function is used for the purpose of timing model calculations:

• there is no paced effect (because the timed item is not an animation or does not specify an animation effect), or
• the referenced property is not one of the target properties of the paced effect, or
• the referenced property is not interpolable, or
• the referenced property is not a valid property.

3.12.6 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. 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.
3. Let scaled fraction be the result of evaluating the timed item's timing function with iteration fraction as the input time fraction.
4. Return the result of evaluating scaled fraction * iteration duration.

3.13.3 Parallel timing groups

A parallel timing group is a type of timing group that schedules its child timed items such that they play simultaneously.

3.13.4 Sequence timing groups

A sequence timing group is a type of timing group that schedules its child timed items such that they play in turn following their order in the group. This ordering is achieved by adjusting the start time of each child timed item in the group.

3.13.4.1 The start time of children of a sequence timing group

The start time of a child timed item of a sequence timing group 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 timed item 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 a sequence timing group 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.

Need to define if events fire in this case.

This section is non-normative.

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

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 a timed item 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 a local time less than start delay (e.g. start delay - 1) and 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 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. Not all properties may be animated by an animation effect. Properties that may be animated by an animation effect are defined as animatable. The set of animatable properties is is defined in section 4.5 Animatable properties.

An animation effect that targets a property that is not animatable will have no effect on the property. However, an animation that applies such an animation effect will still exhibit the usual behavior for a timed item such as firing timing events and occupying time in a sequence timing group.

4.1.2 Target property types

The specific operations involved in animating a target property differ based on the property type. For example, the specific procedure for animating a property that specifies a color will differ from a property that specifies a length. Each animatable property defines one or more property types to use when animating.

In order to produce a smooth change between property values, a procedure for interpolation is required. A given property type is interpolable if there is a procedure defined to interpolate between two values of that type.

In order to support accumulation and additive composition, a procedure for addition is required. A given property type is additive if there is a procedure defined to add two values of that type.

An initial list of property types and their procedures for interpolation and addition is given in section 4.6 Animation of property types. In addition to this initial list, specifications that define CSS properties may provide additional property types to define the procedures for interpolation and addition of the values of those properties.

4.1.3 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. Before being applied to the target properties, these intermediate animation values are composed together using the process defined in section 4.2 Combining animations.

An intermediate animation value is established by first calculating an unaccumulated animation value and then applying accumulation behavior.

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 animation priority specified for A and B so that lower priorities sort first.
   2. Sort A and B by the player start time of the associated player of each of A and B so that earlier times sort first.
   3. Sort by the player sequence number so that lower sequence numbers sort first.
   4. Sort A and B in tree order.

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. The initial underlying value is the base value of the target property as defined in section 4.2.4 Combining with other styles: the override stylesheet.

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 animation effect that produced the intermediate animation value and is called the composition operation.

This specification defines two common composition 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 property types where addition is defined such that it is not commutative, the order of the operands is underlying value + intermediate animation value.

If intermediate animation value and underlying value are not of the same property type, or if they are of the same property type but that property type is not additive, replace behavior is applied.

4.2.4 Combining with other styles: the override stylesheet

Applying a composited value to a property depends on establishing an override stylesheet.

The override stylesheet contains composited animation values and acts with a higher priority than all other stylesheets. However, !important rules from all other stylesheets act with a higher priority than the override stylesheet. The override stylesheet is regenerated each time the animation model is updated (see section 4.1 Animation effects).

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

1. Calculate the base value of the property as the value generated for that property by computing the used value [CSS21] for that property in the absence of the override stylesheet.
2. Establish the animation stack for the property (see section 4.2.1 The animation stack).
3. Calculate the composited value of the animation stack passing in the base value of the property as the initial underlying value (see section 4.2.2 Calculating the result of an animation stack).
4. Insert the composited value into the override stylesheet.

4.3.1 The unaccumulated animation value of a keyframe animation effect

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

1. Let target property be the property for which the unaccumulated animation value is to be calculated.
2. If target property is not animatable abort the procedure since the effect cannot be applied.
3. Let time fraction be the time fraction for which the unaccumulated animation value is to be calculated.
4. Let underlying value be the current underlying value.
5. Define the neutral value for composition as a value which, when combined with an underlying value using the add composition operation, produces the underlying value.

   Note that this definition does not require determining a suitable zero value for each possible property type. This behavior could be realized, for example, by use of a sentinel value.

6. Let property-specific keyframes be a copy of the list of keyframes specified on the effect.
7. Remove any keyframes from property-specific keyframes that do not have a property value for target property.
8. If property-specific keyframes is empty, return underlying value.
9. If there is no keyframe with a positional offset of 0, create a new keyframe with a positional offset of 0, a property value set to the neutral value for composition, and a composition operation of add, and add it to the beginning of property-specific keyframes.
10. Similarly, if there is no keyframe with a positional offset of 1, create a new keyframe with a positional offset of 1, a property value set to the neutral value for composition, and a composition operation of add, and append it to the end of property-specific keyframes.
11. Iterate over each keyframe in property-specific keyframes and for each keyframe, if:
    • keyframe has a composition operation of add, or
    • keyframe has no composition operation and the composition operation of this keyframe animation effect is add
    perform the following steps:
    1. Let value to add be the property value of target property specified on keyframe.
    2. If the property type of underlying value and value to add is the same and is additive, set the property value of target property for keyframe to underlying value + value to add.
12. If time fraction < 0 and there is more than one keyframe in property-specific keyframes with a positional offset of 0, return the property value for target property of the first keyframe in property-specific keyframes.
13. If time fraction ≥ 1 and there is more than one keyframe in property-specific keyframes with a positional offset of 1, return the property value for target property of the last keyframe in property-specific keyframes.
14. Let start keyframe be the last keyframe in property-specific keyframes whose positional 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), let start keyframe be the last keyframe whose positional offset is 0.
15. Let end keyframe be the next keyframe in property-specific keyframes after start keyframe.
16. Let start offset be the positional offset of start keyframe.
17. Let end offset be the offset of end keyframe.
18. Let interval distance be the result of evaluating (time fraction - start offset) / (end offset - start offset)
19. Return the result of interpolating between the property values defined for start keyframe and end keyframe using the procedure defined for their property type with interval distance as the interpolation parameter.

Note that this procedure permits overlapping keyframes. The behavior is that at the point of overlap the output value jumps to the value of 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.3.2 Procedure for evenly distributing keyframes

Whilst the Web Animations model assumes a sorted list of keyframes with specified positional offsets in the range [0, 1] many users of the model require a facility for automatically distributing keyframes when positional offsets are not provided. A procedure for evenly distributing keyframes with unspecified positional offsets is provided below.

Given a list of keyframes whose positional offets are either a real number in the range [0, 1] or unspecified, we define such as list as loosely sorted by offset if, for each keyframe in the list that has a specified offset, the offset is greater than or equal to the offset of the previous keyframe in the list with a specified offset, if any.

Given a list of keyframes, initial keyframe list, that is loosely sorted by offset we can evenly distribute the keyframes with unspecified positional offsets between those frames with specified offsets using the following procedure:

1. Let distributed keyframes be a copy of initial keyframe list.
2. If distributed keyframes contains more than one keyframe and the positional offset of the first keyframe in distributed keyframes is unspecified, set the positional offset of the first keyframe in distributed keyframes to 0.
3. If the positional offset of the last keyframe in distributed keyframes is unspecified, set its positional offset to 1.
4. Set the offset of all keyframes in distributed keyframes without a specified positional offset as so that for a keyframe, k, without a specified offset, if:
   • a is the positional offset of the last keyframe with a specified offset appearing in distributed keyframes before k,
   • b is the positional offset of the first keyframe with a specified offset appearing in pre-processed keyframes after k,
   • n is the number of keyframes between a and b, and
   • i is the index of k among the keyframes between a and b such that the first keyframe has index 1 and the last keyframe has index n;

   then the offset of k is a + (b - a) * i / (n + 1)

5. Return distributed keyframes.

4.4.1 The unaccumulated animation value of a path animation effect

The unaccumulated animation value of a path animation effect for a given time fraction and underlying value is given by the following process:

1. Determine the current path element and element fraction for the given time fraction using the procedure defined in section 4.4.2 Determining the current path element and element fraction.
2. Calculate the rotation value for the current path element and element fraction using the process defined in section 4.4.3 Calculating the rotation value of a path animation effect.
3. Calculate the translation value for the current path element and element fraction using the process defined in section 4.4.4 Calculating the translation value of a path animation effect.
4. Let the transform value be the result of combining the rotation value and translation value by constructing a transform list consisting of the translation value followed by the rotation value.
5. The unaccumulated animation value of the path animation effect depends on the value of its composition operation as follows,

   If the composition operation of this path animation effect is replace,

   the unaccumulated animation value of the effect is transform value.

   Otherwise,

   the unaccumulated animation value of the effect is the result of adding transform value to the underlying value according to the process defined in section 4.6.1.7 The <transform-function> type.

4.4.2 Determining the current path element and element fraction

The current path element and element fraction for a given time fraction, progress, are determined by following the steps corresponding to the first matching condition from below:

If progress is greater than or equal to 1,

the current path element is the last element in the path, and the element fraction is 1.

If progress is less than 0,

the current path element is the first element in the path, and the element fraction is 0.

Otherwise,

1. Let effective element list be a clone of the list of path elements with all moveto elements removed.
2. Let time index be progress multiplied by the number of elements in effective element list.
3. Let current element be the element in the effective element list at the index given by floor(progress).
4. Let element fraction be the value given by progress - floor(progress) .

4.4.3 Calculating the rotation value of a path animation effect

For a given path element and element fraction, the rotation value at that point is calculated according to the steps corresponding to the first matching condition from below:

If the automatic rotation flag is not set,

the rotation value of the given path element is the rotation angle.

Otherwise,

the rotation value of the current element is the sum of:

• the angle of the tangent vector of the given path element at the point selected in section 4.4.4 Calculating the translation value of a path animation effect for the purpose of calculating the translation value; and
• the rotation angle.

For continuous path elements (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.

What does “different from” mean here?

For moveto path elements, which are discontinuous, the angle of the tangent vector for the purpose of these calculations is always an integer multiple of 2π.

Any multiple?

At non-smooth junction points, the angle of the tangent vector for the purpose of these calculations is determined by the tangent to the curve after the junction.

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 elements 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 elements.

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.

Please see section B. Algorithms for path animation effects for a non-normative treatment of this topic.

4.4.4 Calculating the translation value of a path animation effect

For a given path element and element fraction, the translation value is determined using the following procedure:

1. Let length be the length of the given path element.

   Need a reference to how this is calculated even if it's just a pointer to SVG (which says pretty much nothing).

2. Let element distance be the result of evaluating element fraction × length.

3. Let point be the unique point along the current element which is element distance along the path from the start of the path.

   What is the significance of “unique point” here?

4. The translation value is the translation transform that transforms the point at the start of the path to point.

The length of a path element is determined, where possible, via closed-form solutions. For some path elements (e.g. beziers) a closed-form solution is not generally possible, and approximations should be used.

The length of a moveto element is always 0.

Please see section B. Algorithms for path animation effects for a full non-normative treatment of this topic.

4.5.1 CSS Properties

Unless specified otherwise, all CSS properties are animatable. Examples of properties which are explicitly marked as not animatable are those defined in [CSS3-TRANSITIONS] and [CSS3-ANIMATIONS].

This also applies to CSS properties defined in SVG [SVG11] which are likewise animatable except where explicitly noted otherwise.

4.5.2 SVG Attributes

There are a number of SVG attributes which do not map to CSS properties but which are nevertheless animatable. The procedures for animating these attributes are defined in a forthcoming SVG Animation specification.

The specific procedures for interpolation and addition of animation values for common CSS value types are defined below.

For a given pair of animation values, the procedures depend on the types of the two values. If there is no set of procedures matching the particular types of the two values, the default procedures defined in section 4.6.7 Default animation procedures is used.

In CSS transitions the interpolation procedure is determined by the property, not the specific values. Do we really want to define this in terms of the values in question? That seems to remove flexibility to make different properties with the same value types interpolate differently or turn off additive behavior on a per-property basis.

For each set of procedures, a common notation is used. For interpolation,

• V_res is the result of the interpolation operation,
• p is the interpolation parameter, and
• V_start and V_end are the animation values representing the start and end of the interpolation interval respectively.

For addition,

• V_res is the result of the addition operation,
• V_a and V_b are the two animation values to be added.

When an addition procedure is not commutative, V_a represents the first term of the operation and V_b represents the second.

4.6.1 Animation of like types

When the types being interpolated or animated equal the following specific procedures are used.

Note that in all cases, if the result of the addition is specified by a calc expression and the units of V_a and V_b are related by a constant scalar multiple then the result of the calc expression is evaluated as defined in [CSS3-VALUES] before being returned.

What does “being returned” mean here?

4.6.2 Animation of non-matching primitive types

In general, non-matching primitive types cannot be interpolated or added. Non-matching primitive types may only be interpolated or added if the property value they are defined on allows both those types, for example <length> and <percent>. In these cases, the CSS calc() function as defined in [CSS3-VALUES] is used.

For interpolation:

V_res = calc((1 - p) * V_start + p * V_end).

For addition:

V_res = calc(V_a + V_b).

4.6.3 Animation of keywords and primitive types

If keyword value is be defined as equivalent to a primitive type, either directly, or via some intermediate calculation, the equivalent primitive type is be used, and interpolation and addition calculated are defined in section 4.6.1 Animation of like types or section 4.6.2 Animation of non-matching primitive types.

In the case that a keyword maps onto a finite ordered list of values with a determinable spacing between them, then a step-wise interpolation is used. For example, the font-weight property accepts an ordered list of values from 100 to 900 in steps of 100. The interpolation in this case is defined as ((1 - p) * V_start + p * V_end), rounded to the nearest member of the list. Addition in this case is defined as (V_a + V_b), clamped to remain within the specifed list of values.

In all other cases, the keyword value is not interpolable. Result of add is the right hand side.

4.6.4 Animation of shorthand properties

Shorthand properties are animated as defined in [CSS3-TRANSITIONS].

4.6.5 Animation of CSS calc expressions

For interpolation:

V_res = calc((1 - p) * V_start + p * V_end).

For addition:

V_res = calc(V_a + V_b).

4.6.6 Animation of transform lists

Interpolation of CSS and SVG transform lists is performed as defined in [CSS3-TRANSFORMS]

Addition of CSS and SVG transform lists is performed by appending V_b to V_a.

4.6.7 Default animation procedures

In the case that no specific set of procedures matches the pair of animation values, the following default procedures are used.

Note that the neutral value for composition does not match any value type and thus all calculations involving the neutral value for composition will use the default algorithms.

Given the output p of a timing function, the result V_res of interpolating between two values, V_start and V_end is given by

If 0 ≤ p < 0.5

V_res = V_start

Otherwise,

V_res = V_end

Addition is between two values V_a and V_b. The result V_res is given by

V_res = V_b

V_res = V_a

4.7.1 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 Combining with other styles: the override stylesheet).

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 initially the same as that defined for animation effects in section 4.2.1 The animation stack. However, custom effects may also override this ordering through a priority property associated with the effect. This priority property, if defined, specifies the order in which the callbacks are executed such that the callback of the custom effect with the least priority is executed first.

In deciding which of two custom effects, A and B, should be executed first, the following rules are applied.

1. Sort A and B based on their priority properties such that lower priorities are sorted first. If either does not have a defined priority, then treat the priority as being zero for the purposes of sorting.
2. If A and B have the same priority, sort A and B using the procedure defined for sorting animation effects in section 4.2.1 The animation stack.

Items sorted earlier are executed before those sorted later.

5.7.1 Seeked event dispatch

Seeked event dispatch is a mode of event dispatch that produces at most one timing event per timed item by comparing whether the timed item was active or not at some initial moment and at some final moment.

To facilitate this, each timed item has an associated previous active state property that initially has the value inactive.

For a given timed item the events queued as a result of performing seeked event dispatch at uneased local time t is as follows:

1. Let timeline time be the time value of the timeline with which the timed item is associated. The procedures for calculating the timeline time from a timed item's uneased local time or the current time of a player are defined in section 5.3 Inverse timing calculations.
2. Let iteration index be the result of calculating the current iteration at t.
3. Let timeline time be the time value of the timeline with which the timed item is associated. The procedures for calculating the timeline time from a timed item's uneased local time or the current time of a player are defined in section 5.3 Inverse timing calculations.
4. Let current active state be active if the timed item is active at t, and inactive otherwise.
5. The events to be queued depend on comparing the current active state and the timed item's previous active state as follows.

   If the timed item's previous active state is active and current active state is inactive,

   Queue a new timingend event with parameters:

   • event local time: t
   • event timeline time: timeline time
   • event iteration index: iteration index
   • seeked dispatch flag: true

   If the timed item's previous active state is inactive and current active state is active,

   Queue a new timingstart event with parameters:

   • event local time: t
   • event timeline time: timeline time
   • event iteration index: iteration index
   • seeked dispatch flag: true

6. Let the timed item's previous active state be current active state.

For timing groups, this procedure is applied recursively to all child timed items. The resulting events are sorted using the sequence defined in section 5.6 Sequence of events.

Note that seeked event dispatch is only defined for timed items associated with a player. Timed items not associated with a player dispatch timingcancel events as defined in section 5.7.3 Event dispatch and time adjustments.

5.7.2 Event dispatch and seeking a player

When a seek is performed on a player (see section 3.5.2.6 Performing a seek) seeked event dispatch is applied.

Prior to performing the seek, the previous active state of each timed item that is either the source content of the player or a descendent of the source content is updated to reflect whether the timed item is active or not at the moment prior to performing the seek.

If the time adjusted flag of the player has been set, no update of the previous active state of the source content and its descendants is performed.

The timeline time used in the seeked event dispatch procedure is simply the seek time.

After completing the seek, the previous sample time of the player is updated to reflect the seek time and the time adjusted flag, if set, is cleared.

5.7.3 Event dispatch and time adjustments

Associated with each player is a time adjusted flag that is initially false.

The time adjusted flag is set to true whenever any of the following actions is performed on any of the timed items associated with the player.

• The parent timing group changes identity including changes to and from null. This includes timed items that become newly associated with the player or likewise cease to be associated with the player.
• The following timing parameters are modified:
  • start delay
  • iteration start
  • iteration count
  • iteration duration
  • active duration
  • playback rate
  • playback direction

  Note that the fill mode and timing function associated with a timed item are not included in this list since they do not effect uneased timing.

  This behavior extends only to actual changes to the values. Setting a property to its current value—for example, by using the script interface— does not cause the flag to be set.

• The sequence of children within a timing group is changed.

The time adjusted flag is cleared after events are queued for the given player.

When queuing events for a player, if the time adjusted flag of the player is set, seeked event dispatch is used for all timed items associated with the player.

5.7.4 Event dispatch and unattached timed items

A timed item that is not associated with a player is an unattached timed item.

Each time an operation is performed that causes a timed item that was associated with a player to become an unattached timed item it is appended to the end of a queue of unattached timed items associated with the player.

Should an unattached timed item later become associated with a player it is removed from any queue of unattached timed items it may be present in. As a result a timed item will only ever appear in at most one queue of unattached times and never twice in the same queue.

When events are queued as a result of sampling, the following steps are performed for all timed items in the queue of unattached items for each player that is sampled.

1. If the previous active state of the timed item is active,
   1. Queue a new timingcancel event with all parameters set to null.
   2. Set the previous active state to inactive.
2. Remove the timed item from the queue of unattached timed items.

Note that timingcancel events are not dispatched when seeking a player. As a result it is possible, using the script interface to make a batch of changes to the arrangement of timed items including seeking and provided all timed items are associated with a player when the script block completes no timingcancel events will be dispatched.

5.7.5 Event dispatch and extended delays

If, whilst sampling a timeline, more than 30 events are queued, the user agent may employ seeked event dispatch for all timed items associated with the timeline.

30 is somewhat arbitrary. Need feedback both from implementations (on the most constrained device, when does this start being burdensome?) and authoring (what is the minimum guarantee necessary to cover most regular content?)

6.1.1 Attributes

currentTime of type double, readonly, nullable

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

For a document timeline this will never be negative and represents the number of seconds since the document with which this timeline is associated was ready to fire its load event.

6.1.2 Methods

play

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

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

Similarly, the startTime attribute will be set to the value of this object's currentTime attribute at the moment the method was called, or, if currentTime is null, zero.

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

The currentTime attribute of the Player 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.

We will likely change this interface to the following format:

Promise play(optional TimedItem? source = null);
Player  playNow(optional TimedItem? source = null);

Under this arrangement play would begin at the next possible moment whilst attempting to ensure that the animation begins from the first frame. This allows implementations to make adjustments for vsync or overhead in triggering the animation in another process.

The play callback passes the created Player as the argument to the Promise's fulfill callback.

playNow matches the existing definition of the function and causes the start time of the player to be set to this timeline's currentTime even though this may cause the first part of the animation to be dropped.

Parameter	Type	Nullable	Optional	Description
source	TimedItem	✔	✔ (null)	The source content to assign to the newly-created Player object. The source attribute of the created Player 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 Player object.

Return type: Player

getCurrentPlayers

Returns the set of Player 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<Player>

toTimelineTime

Returns the time value, otherTime, from another Timeline also tied to the global clock, other, converted to a time value relative to this timeline's zero time.

Returns null if:

• this timeline is not started, or
• other is not started.

Note that unlike currentTime, this method may return a negative time value if otherTime occurred prior to this timeline's zero time.

Furthermore, negative values for otherTime are also allowed.

If this timeline records the time value of the global clock at its zero time as global clock offset, and so does other as other global clock offset, then the result of this method is simply:

other global clock offset + otherTime - global clock offset

Exceptions:

DOMException of type InvalidNodeTypeError

Raised if other is a timeline that is not tied to the global clock.

Parameter	Type	Nullable	Optional	Description
otherTime	double	✘	✘
other	Timeline	✘	✘

Return type: double, nullable

toTimelineTime

Returns the number of seconds between when event was fired and this timeline's zero time.

Since the timeStamp attribute of the Event interface specified in [DOM-LEVEL-3-EVENTS] is not guaranteed to be monotonically increasing, implementations should record alongside each event the time value of the global clock when the event is dispatched so that it can be converted to an accurate time value here.

Unlike currentTime, this method may return a negative time value if the event was fired prior to this timeline's zero time.

Returns null if this timeline is not started.

This might be deferred to a later version.

Parameter	Type	Nullable	Optional	Description
event	Event	✘	✘

Return type: double, nullable

6.2.1 Attributes

source of type TimedItem, nullable

The source content associated with this player.

A player can only be associated with at most one timed item, and likewise, a timed item can only be associated—either directly or via an ancestor—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 Timeline, readonly

The timeline associated with this player.

startTime of type double

The start time of this player.

currentTime of type double

The effective current time of this player. Setting this attribute follows the procedure defined in section 3.5.2.6 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

The paused state of this player. Setting this attribute follows the procedure defined in section 3.5.2.5 Updating the paused state.

6.3.1 Attributes

localTime of type double, readonly, nullable

The local time of this timed item.

localTime will be null if this timed item is not directly or indirectly associated with a player or if it has a parent timing group that is not in effect.

currentIteration of type unsigned long, readonly, nullable

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

specified of type Timing, readonly

Returns the input timing properties for this timed item.

Representing these parameters has been a particularly contentious topic.

The current arrangement:

• requires defining both a Timing interface and a TimingInput dictionary type which increases the API surface area somewhat
• means that setting the value occurs at a different place (anim.specified.iterationDuration) to reading the value (typically, anim.iterationDuration)
• opens up questions about whether Timing 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). It is also not permitted by WebIDL.

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

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

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

interface TimedItem : EventTarget {
   // Timing
   attribute double   startDelay;
   attribute FillMode fillMode;
   attribute Duration iterationDuration;
   attribute Duration activeDuration;
   attribute double   playbackRate;
   // ...
   
   // Scheduled time
   readonly attribute double              startTime;
   readonly attribute unrestricted double endTime;
};

interface Duration {
  double    sec;
  DOMString string;
}

Usage is as follows:

var specifiedDur  = anim.iterationDuration.string; // "auto"
var calculatedDur = anim.iterationDuration.sec; // 5

// Update duration to 3s
anim.iterationDuration.sec = 3;
// anim.iterationDuration.string -> "3s"

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

// Reset to auto
anim.iterationDuration.string = "auto";  
// anim.iterationDuration.sec -> 5

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

startTime of type double, readonly

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

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

iterationDuration of type unrestricted double, readonly

The iteration duration of this timed item.

Unlike the iterationDuration attribute of the Timing interface or TimingInput dictionary, this attribute returns the calculated value of the iteration duration. If specified.iterationDuration 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 iterationDuration attribute of the specified member of this interface.

activeDuration of type unrestricted double, readonly

The active duration of this timed item.

As with iterationDuration, this attribute returns the calculated value of the active duration. If specified.activeDuration is the string auto or any unsupported value, this is the result of evaluating the active duration using the procedure defined in section 3.10.2 Calculating the active duration. Otherwise, it is the value specified for specified.activeDuration.

This value may be changed by setting the activeDuration attribute of the specified member of this interface.

endTime of type unrestricted double, readonly

The upper bound of the active interval expressed in seconds in inherited time space.

endTime is calculated as start time + start delay + activeDuration

Note that while the endTime is read-only, it can be set indirectly as follows:

// Set endTime to 't'
var t = 6;
timing.specified.activeDuration =
  t - anim.startTime - anim.specified.startDelay;

parent of type TimingGroup, readonly, nullable

The parent timing group of this timed item or null if this timed item does not have a parent timing group.

Should this be parentGroup?

previousSibling of type TimedItem, readonly, nullable

The previous sibling of this timed item.

nextSibling of type TimedItem, readonly, nullable

The next sibling of this timed item.

player of type Player, readonly, nullable

The player associated with this timed item—either directly or indirectly. This object can be used to perform play control such as pausing or rewinding on this timed item and all other timed items in the same hierarchy.

This will be null if this timed item is not associated with a player.

onstart of type EventHandler

The event handler for the timingstart event.

oniteration of type EventHandler

The event handler for the timingiteration event.

onend of type EventHandler

The event handler for the timingend event.

oncancel of type EventHandler

The event handler for the timingcancel event.

6.3.2 Methods

before

Inserts items before this timed item.

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

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

item.before(item); // throws HierarchyRequestError

Parameter	Type	Nullable	Optional	Description
items	TimedItem...	✘	✘

Return type: void

after

Inserts items after this timed item.

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

Parameter	Type	Nullable	Optional	Description
items	TimedItem...	✘	✘

Return type: void

replace

Replaces this TimedItem with the passed in items.

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

Parameter	Type	Nullable	Optional	Description
items	TimedItem...	✘	✘

Return type: void

remove

Removes this timed item from its parent timing group.

No parameters.

Return type: void

6.4.1 Attributes

startDelay of type double

The start delay which represents the number of seconds from a timed item's start time to the start of the active interval.

fillMode of type FillMode

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

iterationStart of type double

The timed item's iteration start property.

A finite real number greater than or equal to zero representing the number of iterations into the timed item at which to begin. For example, a value of 0.5 would cause the timed item 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 iterationCount is effectively added to the iterationStart such that a timed item with an iterationStart of ‘0.5’ and iterationCount of ‘2’ would still repeat twice however it would begin and end half-way through the timed item'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 accumulate property of ‘accumulate’.

iterationCount of type unrestricted double

The timed item's iteration count property.

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

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

iterationDuration 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 timed item.

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

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

activeDuration of type (unrestricted double or DOMString)

The active duration of this timed item, that is, the length of its active interval.

The string value auto is used to indicate that the active duration is calculated using the procedure defined in section 3.10.2 Calculating the active duration. Otherwise, if a real number greater than or equal to zero (including positive infinity) is specified, that procedure is ignored and the value provided here is used for all timing model calculations that refer to the active duration.

Real numbers less than zero and strings other than the value 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 timed item's playback rate property.

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

direction of type PlaybackDirection

The playback direction of the timed item as specified by one of the PlaybackDirection enumeration values.

timingFunction of type DOMString

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

The acceptable values and their meanings are those defined for the transition-timing-function property in CSS Transitions [CSS3-TRANSITIONS].

In addition to the values defined in CSS Transitions, this method extends the steps() function notation to allow ‘middle’ as a transition point keyword (e.g. steps(3, middle)). Similarly, the keyword ‘steps-middle’ is recognized and given the meaning steps(1, middle).

Strings that specify a cubic-bezier() timing function result produce a cubic Bézier timing function. Strings that specify a steps() function produce a step timing function. Strings that specify apaced() timing function result produce a paced timing function.

Unrecognized string values are treated as if the linear keyword was specified for the purpose of timing model calculations.

6.5.1 Dictionary TimingInput Members

startDelay of type double, defaulting to 0

The specified start delay.

See the description of the startDelay attribute on the Timing interface.

fillMode of type FillMode, defaulting to "forwards"

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

Note that in both CSS Animations [CSS3-ANIMATIONS] and SVG [SVG11] the default fill mode is "none". Web Animations differs in this regard since it was determined that when generating animations from script, forwards filling is the more commonly-desired behavior.

Some feedback suggests the default here should be "both".

iterationStart of type double, defaulting to 0.0

The timed item's iteration start property.

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

iterationCount of type unrestricted double, defaulting to 1.0

The timed item's iteration count property.

See the description of the iterationCount attribute on the Timing interface.

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

The iteration duration of the timed item.

See the description of the iterationDuration attribute on the Timing interface.

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

The active duration of the timed item.

See the description of the activeDuration attribute on the Timing interface.

playbackRate of type double, defaulting to 1.0

The timed item's playback rate property.

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

direction of type PlaybackDirection, defaulting to "normal"

The playback direction of the timed item.

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

timingFunction of type DOMString, defaulting to "linear"

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

See the description of the timingFunction attribute on the Timing interface.

6.5.2 The FillMode enumeration

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

6.5.3 The PlaybackDirection enumeration

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

6.6.1 Attributes

children of type TimedItemList, readonly

The list of child timed items in the group.

firstChild of type TimedItem, readonly, nullable

The first child of this timing group.

lastChild of type TimedItem, readonly, nullable

The last child of this timing group.

6.6.2 Methods

prepend

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

Parameter	Type	Nullable	Optional	Description
items	TimedItem...	✘	✘

Return type: void

append

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

Parameter	Type	Nullable	Optional	Description
items	TimedItem...	✘	✘

Return type: void

6.6.3 Common definitions for manipulating hierarchies

The next sibling of item not included in a set of timed items, items is determined using the following steps:

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

To remove an item from its parent timing group or player, perform the steps corresponding to the first matching condition from below, if any:

If item has a parent timing group,

Remove item from the parent timing group's list of child timed items.

If item is directly associated with a player,

Disassociate item from the player.

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

1. Remove item from its parent.
2. Insert item to parent's list of child timed items before reference child.

6.7.1 Attributes

length of type unsigned long, readonly

The number of timed items in the list.

6.7.2 Methods

item [index]

Returns the timed item at index. If index is greater than or equal to length returns null.

Parameter	Type	Nullable	Optional	Description
index	unsigned long	✘	✘

Return type: TimedItem, nullable

6.8.1 Constructors

ParGroup

Creates a new ParGroup object using the following procedure:

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

   If timing is a TimingInput object,

   Let timing input refer to timing.

   If timing is a double,

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

   Otherwise (timing is null or undefined),

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

3. Set group.specified to a new Timing 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. Add children to the group by calling group.splice(0, 0, children).

Note that since Timing objects have the same member names as TimingInput dictionaries, it is also possible to pass the specified member of another TimedItem as the timing parameter.

Doing so will cause the Timing object to be treated as a TimingInput dictionary and thus it will effectively be cloned, not shared.

Parameter	Type	Nullable	Optional	Description
children	sequence<TimedItem>	✔	✘	A sequence of timed items to add as children of this group. These children are appended in sequence using the same semantics as the TimingGroup.append method.
timing	(unrestricted double or TimingInput)	✔	✔ (null)	The timing properties or iteration duration of the new timing group.

6.8.2 Methods

clone

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

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

No parameters.

Return type: ParGroup

6.9.1 Constructors

SeqGroup

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

Parameter	Type	Nullable	Optional	Description
children	sequence<TimedItem>	✔	✘
timing	(unrestricted double or TimingInput)	✔	✔ (null)

6.9.2 Methods

clone

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

No parameters.

Return type: SeqGroup

6.10.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 a TimingInput object,

   Let timing input refer to timing.

   If timing is a double,

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

   Otherwise (timing is null or undefined),

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

3. Set animation.specified to a new Timing object whose attributes are assigned the value of the member of the same name on timing input.
4. Assign the animation effect based on the type of effect as follows,

   If effect is an AnimationEffect object or a CustomEffect object,

   Assign animation.effect to effect.

   If effect is a OneOrMoreKeyframes,

   Set animation.effect to a new KeyframeAnimationEffect object constructed by passing effect as the frames parameter and with the other parameters set to their default values.

   Otherwise,

   Set animation.effect to null.

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

Note that as with the constructor for TimingGroups it is possible to pass in a Timing object here (e.g. the specified member of another TimedItem) in which case it will be cloned.

Parameter	Type	Nullable	Optional	Description
element	AnimationTarget	✔	✘	The target element or target pseudo-element. This may be null for animations that do not target a specific element.
effect	(AnimationEffect or CustomEffect or OneOrMoreKeyframes)	✔	✘	The animation effect used to set the effect attribute of the newly-created Animation object. If this parameter is an AnimationEffect object or CustomEffect object, it will shared with any other Animation objects referring to the same AnimationEffect or CustomEffect object. It will not be copied. If this parameter of type OneOrMoreKeyframes, the animation effect of the newly-created Animation will be a newly-created KeyframeAnimationEffect 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 TimingInput)	✔	✔ (null)	The timing properties or iteration duration of the new animation.

6.10.2 Attributes

effect of type (AnimationEffect or CustomEffect), nullable

The animation effect or custom effect to apply. May be null in which case the animation will produce no noticeable effect other than dispatching events (see section 5. Timing events).

target of type AnimationTarget, readonly, 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.

Note that in a future version, AnimationTarget may be extended to allow targetting, for example, a sequence of elements. Therefore, code that is intended to be used with arbitrary Animation objects should test the concrete type of target before using it and not assume that it refers to an Element.

If SVG is extended to allow multiple targets (using, e.g., select="rect") then it might be most natural to represent that in the API by allowing the target to refer to multiple elements. It's something that deserves attention for version 1.

6.10.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 TimingInput object whose members are assigned the value of the attribute with the same name on source.specified.
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 a CustomEffect object,

   If source.effect has a method called clone let cloned effect be the result of calling that method, otherwise 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

6.11.1 Constructors

PseudoElementReference

Creates a new pseudo-element reference using element as the subject and pseudoElement as the pseudo-element to match (e.g. ‘::first-line’).

Parameter	Type	Nullable	Optional	Description
element	Element	✘	✘
pseudoElement	DOMString	✘	✘

6.11.2 Attributes

element of type Element

The element used as the subject for matching a pseudo-element.

Exceptions:

DOMException of type NoModificationAllowedError

Raised on setting if this object is a readonly object.

pseudoElement of type DOMString

The pseudo-element including the initial colon(s). For example, ‘::after’.

Exceptions:

DOMException of type NoModificationAllowedError

Raised on setting if this object is a readonly object.

6.13.1 Attributes

accumulate of type AccumulateOperation

The accumulation operation property of this animation effect as specified by one of the AccumulateOperation constants.

6.13.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

6.14.1 Values

sum

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

none

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

6.15.1 Values

replace

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

add

Corresponds to the add composition operation value such that the animation effect is added to base value it is combined with.

6.16.1 Constructors

KeyframeAnimationEffect

Creates a new KeyframeAnimationEffect object for the given set of keyframes.

Before storing, each of the keyframes in frames is normalized using the procedure in section 6.17.2 Normalizing a Keyframe object.

Parameter	Type	Nullable	Optional	Description
frames	OneOrMoreKeyframes	✘	✘	The set of keyframes used for calculating animation values for this animation effect. The constraints on this parameter and its processing are identical to those for setFrames.
composite	CompositeOperation	✘	✔ ("replace")	The composition operation used to composite this animation with the animation stack, as specified by one of the CompositeOperation enumeration values. This is used for all keyframes that do not specify a composition operation.
accumulate	AccumulateOperation	✘	✔ ("none")	The accumulation operation used to define the way animation values build from iteration to iteration.

6.16.2 Attributes

composite of type CompositeOperation

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

This is used for all keyframes that do not specify a composition operation.

6.16.3 Methods

getFrames

Returns the keyframes that make up this effect as a sequence of Keyframe objects.

Note that the normalization applied to the list of keyframes as defined in section 6.16.4 Normalizing the list of keyframes does not affect the value returned by this method.

No parameters.

Return type: sequence<Keyframe>

setFrames

Replaces the set of keyframes that make up this effect.

Upon setting, each keyframe in frames is normalized using the procedure in section 6.17.2 Normalizing a Keyframe object before storing.

Before being used by the animation model, the set of frames associated with this effect is normalized using the procedure defined in section 6.16.4 Normalizing the list of keyframes.

As a result of the normalization of the list, if frames is not loosely sorted by offset this effect will not contribute to the final composited value.

Parameter	Type	Nullable	Optional	Description
frames	OneOrMoreKeyframes	✘	✘

Return type: void

6.16.4 Normalizing the list of keyframes