Overview.src.html

<h1>Web Animations</h1>
<pre class='metadata'>
Status: ED
Shortname: web-animations
ED: http://w3c.github.io/web-animations/
TR: http://www.w3.org/TR/web-animations/
Previous version: http://www.w3.org/TR/2014/WD-web-animations-20140605/
Previous version: http://www.w3.org/TR/2013/WD-web-animations-20130625/
Version history: https://github.com/w3c/web-animations/commits/master
Level: 1
Group: fxtf
Editor: Brian Birtles, Mozilla Japan, bbirtles@mozilla.com
Editor: Shane Stephens, Google Inc, shans@google.com
Editor: Alex Danilo, Google Inc, adanilo@google.com
Editor: Tab Atkins, Google Inc, jackalmage@gmail.com
Abstract: This specification defines a model for synchronization and
    timing of changes to the presentation of a Web page.
    This specification also defines an application programming interface
    for interacting with this model and it is expected that further
    specifications will define declarative means for exposing these
    features.
Ignored Terms: double, boolean, DOMString, unsigned long, unrestricted double, (animationeffect or effectcallback), SVGPathSegList, (unrestricted double or DOMString)
Link Defaults: dom-core-ls (interface) event, dom-core-ls (interface) document, cssom-1 (interface) pseudoelement
</pre>

<link href='http://dev.w3.org/fxtf/default.css' rel='stylesheet' test='text/css'>
<link href='web-animations.css' rel='stylesheet' type='text/css'>
<script src='MathJax/MathJax.js?config=MML_SVGorMML,local/local' type='text/javascript'></script>

<h2 id="introduction">Introduction</h2>
<div class='informative-bg'><em>This section is non-normative</em>

Web Animations defines a model for supporting animation and
synchronization on the Web platform.
It is intended that other specifications will build on this model and
expose its features through declarative means.
In addition, this specification also defines a programming interface to
the model that may be implemented by user agents that provide support
for scripting.

<h3 id="use-cases">Use cases</h3>

The Web Animations model aims at two broad areas of application:

:   User interface effects
::  Animation can be used to give visual clues and feedback to make
    a user interface more readily comprehensible.

    For example, a user action results in a table row being
    removed to represent an item being removed from a shopping cart.cd -
    In such a case, fading the row to transparent and then shifting
    the subsequent rows up to fill the space over a few hundred
    milliseconds provides the user with clear feedback as to the
    results of their action as opposed to instantly removing the row
    from the DOM.

    To support this scenario not only are the animated effects of
    fading and shifting required, but so is synchronization, both
    between the animations, and between animations and scripted
    actions (removing the table row from the DOM after the animations
    have completed).

:   Storytelling and visualization
::  Another type of animation uses the animated effect to convey
    a story or represent some information.
    Unlike user interface effects which are largely a presentational
    adjunct to the content, these animations form an essential part of
    the content presented to the user.

    For example, in an animated cartoon two cats fly through space
    to another planet leaving a rainbow trail behind them.
    After arriving at the planet a change of scene occurs and the user
    should decide whether or not the cats enter a magic mountain by
    selecting one of two preset destinations in the scene.

    This scenario requires the following features:

    *   animated effects for moving characters along a path as well as
        warping a path (the rainbow trail),
    *   synchronization that allows some actions to happen
        simultaneously (the two cats moving) and others in sequence
        (the change of scene),
    *   play control to allow rewinding the cartoon, or changing its
        playback rate to accommodate particular learning or
        accessibility needs,
    *   the ability to trigger animations in response to user input

    Similar use cases in this category include visualising physical
    phenomena such as spring motion for educational purposes,
    or visualising data such as the prevalence of a disease over
    a geographical space over a year whereby animation is used to
    present the time-based component of the data.

<h3 id="relationship-to-other-specifications">Relationship to other specifications</h3>

CSS Transitions [[CSS3-TRANSITIONS]], CSS Animations [[CSS3-ANIMATIONS]], and
SVG [[SVG11]] all provide mechanisms that
generate animated content on a Web page.
Although the three specifications provide many similar features,
they are described in different terms.
This specification proposes an abstract animation model that
encompasses the common features of all three specifications.
This model is backwards-compatible with the current behavior of these
specifications such that they can be defined in terms of this model
without any observable change.

The animation features in SVG 1.1 are defined in terms of SMIL
Animation [[SMIL-ANIMATION]].
It is intended that by defining SVG's animation features in terms of
the Web Animations model, the dependency between SVG and SMIL
Animation can be removed.

As with Timing control for script-based animations (commonly referred
to as &ldquo;requestAnimationFrame&rdquo;) [[ANIMATION-TIMING]],
the programming interface component of this specification allows
animations to be created from script.
The animations created using the interface defined in this
specification, however, once created, are executed entirely by the
user agent meaning they share the same performance characteristics as
animations defined by markup.
Using this interface it is possible to create animations
from script in a simpler and more performant manner.

The time values used within the programming interface
correspond with those used in Timing control for script-based
animations [[ANIMATION-TIMING]] and their execution order is defined
such that the two interfaces can be used simultaneously without conflict.

The programming interface component of this specification makes
some additions to interfaces defined in HTML5 [[HTML5]].

<h3 id="overview-of this-specification">Overview of this specification</h3>

This specification begins by defining an abstract model for animation.
This is followed by a programming interface defined in terms of the
abstract model.
The programming interface is defined in terms of the abstract model
and is only relevant to user agents that provide scripting support.

</div>

<h2 id="web-animations-model-overview">Web Animations model overview</h2>

<div class='informative-bg'><em>This section is non-normative</em>

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

:   Timing model
::  Takes a moment in time and converts it to a proportional distance
    within a single iteration of an animation called the <em>time
    fraction</em>.
    An <em>iteration index</em> is also generated for animations
    that vary as they repeat.
:   Animation model
::  Takes the <em>time fractions</em> and <em>iteration indices</em>
    produced by the timing model and converts them into a series of values
    to apply to the target properties and attributes.

Graphically, this flow can be represented as follows:
<div class="figure">
<img src="img/timing-and-animation-models.svg" width="600" alt="Overview of the operation of the Web Animations model.">
</div>
<p class="caption">
Overview of the operation of the Web Animations model.<br>
The current time is input to the timing model which produces a time
fraction and an iteration index.<br>
These parameters are used as input to the animation model which produces
the values to apply.<br>
</p>

For example, consider an animation that:

*   starts after 3 seconds
*   runs twice,
*   takes 2 seconds every time, and
*   changes the width of a rectangle from 50 pixels to 100 pixels.

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

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

</div>

<h2 id="timing-model">Timing model</h2>

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

<h3 id="the-timing-model-at-a-glance">The timing model at a glance</h3>

<div class='informative-bg'>

<em>This section is non-normative</em>

Two features characterise the Web Animations timing model: it is
<em>stateless</em> and it is <em>hierarchical</em>.

<h4 id="stateless">Stateless</h4>

The Web Animations timing model operates by taking an input time and
producing an output time fraction.
Since the output is based solely on the input time and is independent
of previous inputs, the model may be described as stateless.
This gives the model the following properties:


:   Frame-rate independent
::  Since the output is independent of previous inputs, the rate at
    which the model is sampled will not affect its progress.
    Provided the input times are proportional to the progress of
    real-world time, animations will progress at an identical rate
    regardless of the capabilities of the device running them.
:   Direction-agnostic
::  Since the sequence of inputs is insignificant, the model is
    directionless.
    This means that the model can be sampled in reverse or even in
    a backwards and forwards pattern without requiring any specialized
    handling.
:   Constant-time seeking
::  Since each input is independent of the previous input, the
    processing required to perform a seek operation, even far into the
    future, is at least potentially constant.

There are a few exceptions to the stateless behavior of the timing
model.

Firstly, a number of methods defined in the <a
href="#programming-interface" section>programming interface</a> to the model
provide play control such as pausing an animation.
These methods are defined in terms of the time at which they are
called and are therefore stative.
These methods are provided primarily for convenience and are not part
of the core timing model but are layered on top.

Similarly, the <a href="#reaching-the-end" section>finishing behavior</a> of
players means that dynamic changes to the end time of
the media (source content) of a player may produce a different result
depending on when the change occurs.
This behavior is somewhat unfortunate but has been deemed intuitive
and consistent with HTML.
As a result, the model can only truly be described as stateless
<em>in the absence of dynamic changes to its timing properties</em>.

Finally, each time the model is sampled, it can be considered to
establish a temporary state.
While this temporary state affects the values returned from the <a
href="#programming-interface" section>programming interface</a>, it has no
influence on the subsequent samples and hence does not conflict with
the stateless qualities described above.

<h4 id="hierarchical">Hierarchical</h4>

The other characteristic feature of the Web Animations timing model is
that time is inherited.
Time begins with a monotonically increasing time source and cascades
down a number of steps to each animation.
At each step, time may be shifted backwards and forwards, scaled,
reversed, paused, and repeated.

<div class="figure">
  <img src="img/time-hierarchy.svg" width="600"
            alt="A hierarchy of timing nodes">
</div>
<p class="caption">
  A hierarchy of timing nodes.
  Each node in the tree derives its time from its parent node.
  At the root of the tree is the global clock.
</p>

A consequence of this hierarchical arrangement is that complex
animation arrangements can be reversed, scheduled, accelerated and so
on as a whole unit since the manipulations applied to the parent
cascade down to its <a>descendants</a>.
Furthermore, since time has a common source, it is easy to synchronize
animations.

</div>

<h3 id="timing-model-concepts">Timing model concepts</h3>

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

<p class="annotation">
In the future we may have timelines that are based on UI gestures in
which case the connection between time values and milliseconds will be
weakened even further.
</p>

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

Periodically, the user agent will queue a task to update the timing
model in a process called <dfn>sampling</dfn>.
On each <dfn title='single-sample'>sample</dfn> the 
<a>time values</a> of each timing node are updated.

Note: A more precise definition of when the model is updated when scripting is
    involved is provided in <a
    href="#script-execution-and-live-updates-to-the-model"
    section></a>.

<h3 id="the-global-clock">The global clock</h3>

At the root of the Web Animations timing hierarchy is the <a>global
clock</a>.

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

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


<h3 id="timelines">Timelines</h3>

A <dfn>timeline</dfn> provides a source of <a>time values</a> for the
purpose of synchronization.

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

<p class="annotation">
  Note that we anticipate that other types of timelines may be introduced
  in the future that are not tied to the global clock.
  For example, a timeline whose time values are related to the progress of
  a UI gesture.
</p>

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

<h4 id="the-document-timeline">The document timeline</h4>

Each document has a <a>timeline</a> called the <dfn>document
timeline</dfn>.
The <a>time values</a> of the <a>document timeline</a> are calculated
as a fixed offset from the <a>global clock</a> such that the <a>zero
time</a> corresponds to the <a
href="http://www.w3.org/TR/navigation-timing/#dom-performancetiming-navigationstart">
<code>navigationStart</code></a> moment [[!NAVIGATION-TIMING]].
Prior to this moment, the <a>document timeline</a> is
<a title="inactive timeline">inactive</a>.

<div class="informative-bg"><em>This section is non-normative</em>

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

Since the <a>time values</a> of the <a>document timeline</a> are
relative to the <code>navigationStart</code> time,
<code>document.timeline.currentTime</code> will roughly correspond to
<a href="http://www.w3.org/TR/hr-time/#dom-performance-now">
<code>Performance.now()</code></a>
[[HR-TIME]] with the exception that
<code>document.timeline.currentTime</code> does not change within
a script execution block as defined in <a
href="#script-execution-and-live-updates-to-the-model" section></a>.

</div>

<h3 id="players">Players</h3>

<div class="informative-bg"><em>This section is non-normative</em>

The children of a <a>timeline</a> are called <em>players</em>.
A player takes an <a>animation node</a> which is a static
description of some timed behavior and binds it to a <a>timeline</a>
so that it runs.
A player also allows run-time control of the connection between the
<a>animation node</a> and its <a>timeline</a> by providing pausing,
seeking, and speed control.
The relationship between a player and an <a>animation node</a> is
analogous to that of a DVD player and a DVD.
</div>

A <dfn>player</dfn> connects a single <a>animation node</a>, called
its <dfn>source content</dfn>, to a <a>timeline</a> and provides
playback control.
Both of these associations are optional and configurable such that
a <a>player</a> may have no associated <a>source content</a> or
<a>timeline</a> at a given moment.

A <a>player</a>'s <dfn title="player start time">start time</dfn> is the
<a>time value</a> of its <a>timeline</a> when its <a>source content</a>
is scheduled to begin playback. A player's <a
title="player start time">start time</a> is initially
<a>unresolved</a>.

A <a>player</a> also maintains a <dfn>hold time</dfn> <a>time value</a>
which is used to fix the player's output <a>time value</a>, called its
<a>current time</a>, in circumstances such as pausing</a>.
The <a>hold time</a> is initially <a>unresolved</a>.

When a <a>player</a> is created, it is assigned a globally unique
sequence number called the <dfn>player sequence number</dfn>.
This number is used to resolve the sort order of players for a variety
of situations such as combining animations and returning the list of
current players.

Issue: Should this actually be based on when the player is attached to
    a timeline? Or when it leaves the idle state?

<h4 id="setting-the-timeline">Setting the timeline of a player</h4>

The procedure to <dfn>set the timeline of a player</dfn>, <var>player</var>,
to <var>new timeline</var> which may be null, is as follows:

1.  Let <var>old timeline</var> be the current <a>timeline</a> of
    <var>player</var>, if any.
2.  If <var>new timeline</var> is the same object as <var>old timeline</var>,
    abort this procedure.
3.  If <var>new timeline</var> is null and <var>old timeline</var> is not null,
    run the procedure to <a>reset a player's pending tasks</a> on
    <var>player</var>.
    <p class="note">
      Note that if <var>new timeline</var> is not null and <var>player</var> has
      a <a>pending play task</a> or a <a>pending pause task</a> no special
      handling is required: the pending task will run as soon as the
      <a>player</a> is <a>ready</a> even though this may occur at a different
      moment than it might have done with the old timeline.
    </p>
6.  Let the <a>timeline</a> of <var>player</var> be <var>new timeline</var>.
7.  <p class="todo">
      If <var>new timeline</var> is null, ensure that <a>custom effects</a> get
      called with an <a>unresolved</a> <a>time fraction</a> (unless a subsequent
      change in the same script execution context makes this redundant).
    </p>
8.  Run the procedure to <a>update a player's finished state</a> for
    <var>player</var>.

<p class=todo>
  Update this to preserve the player's <a>current time</a>.
</p>

The procedure to <dfn>reset a player's pending tasks</dfn> for <var>player</var>
is as follows:

1.  If <var>player</var> has a <a>pending play task</a>, cancel that task.
2.  If <var>player</var> has a <a>pending pause task</a>, cancel that task.
3.  <a title="reject a Promise">Reject</a> <var>player</var>'s <a>current ready
    promise</a> with a DOMException named "AbortError".
4.  Let <var>player</var>'s <a>current ready promise</a> be the result of
    <a title="create a new resolved Promise">creating a new resolved Promise
    object</a>.

<h4 id="setting-the-source-content">Setting the source content of a
  player</h4>

The procedure to <dfn>set the source content of a player</dfn>,
<var>player</var>, to <var>new content</var> which may be null, is as follows:


1.  Let <var>old content</var> be the current <a>source content</a> of
    <var>player</var>, if any.
2.  If <var>new content</var> is the same object as <var>old content</var>,
    abort this procedure.
3.  If <var>new content</var> is null and <var>old content</var> is not null,
    run the procedure to <a>reset a player's pending tasks</a> on
    <var>player</var>.
4.  If <var>player</var> has a <a>pending pause task</a>, reschedule that task
    to run as soon as <var>player</var> is <a>ready</a>.
5.  If <var>player</var> has a <a>pending play task</a>, reschedule that task
    to run as soon as <var>player</var> is <a>ready</a> to play <var>new
    content</var>.
6.  If <var>new content</var> is not <code>null</code> and
    if <var>new content</var> has a <a>parent animation group</a>,
    <a title="remove an animation node">remove</a> <var>new content</var> from
    its <a>parent animation group</a>.
7.  If <var>new content</var> is not <code>null</code> and
    if <var>new content</var> is the <a>source content</a> of another
    <a>player</a>, <var>previous player</var>, run the procedure to <a>set the
    source content of a player</a> (this procedure) on <var>previous
    player</var> passing null as <var>new content</var>.
8.  Let the <a>source content</a> of <var>player</var> be <var>new
    content</var>.
9.  If <var>old content</var> is not <code>null</code>, queue a task to call any
    <a>custom effects</a> associated with <a>inclusive descendants</a> of
    <var>old content</var> with an <a>unresolved</a> <a>time fraction</a>.
    <div class="issue">
      This is not quite right. If <var>old content</var> is attached to another
      player in the same task then we should probably not do an extra
      callback with <a>unresolved</a>.

      The definition of when <a>custom effects</a> gets called needs to be
      audited and probably rewritten.
    </div>
10. Run the procedure to <a>update a player's finished state</a> for
    <var>player</var>.

<h4 id="the-current-time-of-a-player">The current time of a player</h4>

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

The <a>current time</a> is calculated from the first
matching condition from below:

<div class="switch">

:   If the player's <a>hold time</a> is <a title="unresolved">resolved</a>,
::  The <a>current time</a> is the player's <a>hold time</a>.

:   If <em>any</em> of the following are true:

    1.  the player has no associated <a>timeline</a>, or
    2.  the associated <a>timeline</a> is
        <a title="inactive timeline">inactive</a>, or
    3.  the player's <a title="player start time">start time</a> is
        <a>unresolved</a>.

::  The <a>current time</a> is an <a>unresolved</a> time value.

:   Otherwise,
::

    <blockquote>
      <code><a>current time</a> =
      (<var>timeline time</var> - <a
       title="player start time">start time</a>)
      &times; <a title="player playback rate">playback rate</a></code>
    </blockquote>

    Where <var>timeline time</var> is the current <a>time value</a> of
    the associated <a>timeline</a>.
    The <a title="player playback rate">playback rate</a> value is
    defined in <a href="#speed-control" section></a>.

</div>

<h4 id="setting-the-current-time-of-a-player">Setting the current time of a player</h4>

The <a>current time</a> of a player can be set to a new value to
<em>seek</em> the player.
The procedure for setting the current time is split into two parts.

The procedure to <dfn>silently set the current time</dfn> of
a player, <var>player</var>, to <var>seek time</var> is as follows:

1.  If <var>seek time</var> is an <a>unresolved</a> time value,
    <a href="http://heycam.github.io/webidl/#dfn-throw">throw</a> a
    NotSupportedError.
2.  Update either <var>player</var>'s <a>hold time</a> or <a
    title="player start time">start time</a> as follows:

    <div class="switch">

    :   If <em>any</em> of the following conditions are true:

        *   <var>player</var>'s <a>hold time</a> is
            <a title="unresolved">resolved</a>, or
        *   <var>player</var> has no associated <a>timeline</a> or the
            associated <a>timeline</a> is
            <a title="inactive timeline">inactive</a>, or
        *   <var>player</var>'s
            <a title="player playback rate">playback rate</a> is 0, or
        *   <var>player</var> has a <a>pending pause task</a>

    ::  Set <var>player</var>'s <a>hold time</a> to <var>seek time</var>.

    :   Otherwise,
    ::  Set <var>player</var>'s <a title="player start time">start time</a> to
        the result of evaluating
        <code><var>timeline time</var> - (<var>seek time</var> / <a
            title="player playback rate">playback rate</a>)</code>
        where <var>timeline time</var> is the current <a>time value</a>
        of <a>timeline</a> associated with <var>player</var>.

    </div>

1.  If <var>player</var> has no associated <a>timeline</a> or the associated
    <a>timeline</a> is <a title="inactive timeline">inactive</a>,
    make <var>player</var>'s <a title="player start time">start time</a>
    <a>unresolved</a>.

    <p class=annotation>
      This preserves the invariant that when we don't have an active timeline it
      is only possible to set <em>either</em> the <a>player start time</a>
      <em>or</em> the player's <a>current time</a>.
    </p>

4.  Make <var>player</var>'s <a>previous current time</a> <a>unresolved</a>.

The procedure to <dfn>set the current time</dfn> of a player,
<var>player</var>, to <var>seek time</var> is as follows:

1.  Run the steps to <a>silently set the current time</a> of
    <var>player</var> to <var>seek time</var>.
2.  If <var>player</var> has a <a>pending pause task</a>, cancel the
    task and <a title="resolve a Promise">resolve</a> <var>player</var>'s
    <a>current ready promise</a> with <var>player</var>.
3.  Run the procedure to <a>update a player's finished state</a>
    for <var>player</var>.

<h4 id='setting-the-start-time-of-a-player'>Setting the start time of a player</h4>

The procedure to <dfn>update the player start time</dfn>
of <a>player</a>, <var>player</var>, to
<a title="player start time">start time</a>, <var>new start time</var>,
is as follows:

1.  Let <var>timeline time</var> be the current <a>time value</a> of the
    <a>timeline</a> that <var>player</var> is associated with.
    If there is no <a>timeline</a> associated with <var>player</var> or the
    associated timeline is <a title="inactive timeline">inactive</a>,
    let the <var>timeline time</var> be <a>unresolved</a>.

1.  If <var>timeline time</var> is <a>unresolved</a> and <var>new start
    time</var> is <a title="unresolved">resolved</a>, make <var>player</var>'s
    <a>hold time</a> <a>unresolved</a>.

    <p class=annotation>
      This preserves the invariant that when we don't have an active timeline it
      is only possible to set <em>either</em> the <a>player start time</a>
      <em>or</em> the player's <a>current time</a>.
    </p>

1.  Let <var>previous current time</var> be <var>player</var>'s <a>current
    time</a>.

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

1.  Set <var>player</var>'s <a title="player start time">start time</a> to
    <var>new start time</var>.

1.  Update <var>player</var>'s <a>hold time</a> based on the first matching
    condition from the following,

    <div class="switch">

    :   If <var>new start time</var> is <a title="unresolved">resolved</a>,
    ::  If <var>player</var>'s <a title="player playback rate">playback rate</a>
        is not zero, make <var>player</var>'s <a>hold time</a>
        <a>unresolved</a>.

    :   Otherwise (<var>new start time</var> is <a>unresolved</a>),
    ::  Set <var>player</var>'s <a>hold time</a> to <var>previous current
        time</var> even if <var>previous current time</var> is
        <a>unresolved</a>.

    </div>

1.  If <var>player</var> has a <a>pending play task</a> or
    a <a>pending pause task</a>, cancel that task and
    <a title="resolve a Promise">resolve</a> <var>player</var>'s
    <a>current ready promise</a> with <var>player</var>.

1.  Run the procedure to <a>update a player's finished state</a>
    for <var>player</var>.

<h4 id='waiting-for-source-content'>Waiting for source content</h4>

<div class='informative-bg'>

<em>This section is non-normative</em>

Some operations performed by a <a>player</a> may not occur
instantaneously.
For example, some user agents may delegate the playback of an
animation to a separate process or to specialized graphics hardware
each of which may incur some setup overhead.

If such an animation is timed from the moment when the animation was
triggered there may be a significant jump between the first and second
frames of the animation corresponding to the setup time involved.

To avoid this problem, Web Animations typically begins timing
animations from the moment when the first frame of the animation is
complete.
This is represented by an <a>unresolved</a> <a
title="player start time">start time</a> on the <a>player</a> which becomes
resolved when the player is <a>ready</a>.
Content may opt out of this behavior by setting the <a
title="player start time">start time</a>
to a <a title="unresolved">resolved</a> <a>time value</a>.

</div>

A player is <dfn>ready</dfn> at the first moment where <em>both</em> of the
following conditions are true:

*   the user agent has completed any setup required to begin the playback of
    each <a>inclusive descendant</a> of the player's <a>source content</a>
    including rendering the first frame of any <a>animation</a> with an
    associated <a>animation effect</a> or executing any <a>custom effects</a>
    associated with such an <a>animation</a>.

*   the player is associated with a <a>timeline</a> that is not
    <a title="inactive timeline">inactive</a>.

<h4 id='promise-objects'>Promise objects</h4>

<dfn>Promise</dfn> objects are defined by [[!ECMA-262]], <a
  href="http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promise-objects">section
  25.4</a>.

To <dfn>resolve a Promise</dfn> with <var>value</var>, 
call the \[[Call]] internal method of \[[Resolve]] on the <a
  href="http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promisecapability-records">Promise
capability</a> record for the promise, passing <code>undefined</code> as
<var>thisArgument</var> and (<var>value</var>) as <var>argumentsList</var>.

To <dfn>reject a Promise</dfn> with <var>reason</var>, 
call the \[[Call]] internal method of \[[Reject]] on the <a
  href="http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promisecapability-records">Promise
capability</a> record for the promise, passing <code>undefined</code> as
<var>thisArgument</var> and (<var>reason</var>) as <var>argumentsList</var>.

To <dfn>create a new resolved Promise</dfn> with <var>value</var>, call <a
  href="http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promise.resolve">Promise.resolve</a>,
passing <var>value</var> as <var>x</var>.

<h4 id='the-current-ready-promise'>The current ready promise</h4>

Each <a>player</a> has a <dfn>current ready promise</dfn>.
The <a>current ready promise</a> is initially a resolved <a>Promise</a> created
using the procedure to <a>create a new resolved Promise</a>.

The object is replaced with a new <a>Promise</a> object every time the player
enters the <a>pending play state</a> as well as when the player is
cancelled (see <a href="#cancelling-a-player-section" section></a>).

<div class="note">

    Note that since the same object is used for both pending play and
    pending pause requests, authors are advised to check the state of the
    player when the <a>Promise</a> is resolved.

    For example, in the following code fragment, the state of the player
    will be <a title="running play state">running</a> when the
    <a>current ready promise</a> is resolved.
    This is because the player does not leave the <a>pending play state</a>
    in between the calls to <code>pause</code> and
    <code>play</code> and hence the <a>current ready promise</a> does
    not change.

    <pre class='example sh_javascript'>
        player.pause();
        player.ready.then(function() {
          // Displays 'running'
          alert(player.playState);
        });
        player.play();
    </pre>

</div>

<h4 id='playing-a-player-section'>Playing a player</h4>

The procedure to <dfn>play a player</dfn>, <var>player</var>, is as follows:

1.  Let <var>has pending ready promise</var> be a boolean flag that is
    initially false.
2.  If <var>player</var> has a <a>pending play task</a>,

    1.  Cancel that task.
    2.  Set <var>has pending ready promise</var> to true.

3.  If <var>player</var> has a <a>pending pause task</a>,

    1.  Cancel that task.
    2.  If <var>player</var> has an associated <a>timeline</a> that is not
        <a title="inactive timeline">inactive</a>, perform the following steps:

        1.  Set <var>player</var>'s <a title="player start time">start time</a>
            to the result of evaluating <code><var>timeline time</var> -
            <a>hold time</a> / <a title="player playback rate">playback
            rate</a></code>
            where <var>timeline time</var> is the current <a>time value</a> of
            the <a>timeline</a> associated with <var>player</var>.
        2.  Let <var>player</var>'s <a>hold time</a> be <a>unresolved</a>.

    3.  Set <var>has pending ready promise</var> to true.

4.  Perform the steps corresponding to the <em>first</em> matching
    condition from the following, if any:

    <div class="switch">

    :   If <a>player playback rate</a> &gt; 0 and <em>either</em>
        <var>player</var>'s:

        *   <a>current time</a> is <a>unresolved</a>, or
        *   <a>current time</a> &lt; zero, or
        *   <a>current time</a> &ge; <a>source content end</a>,

    ::  Set <var>player</var>'s <a>hold time</a> to zero.
    :   If <a>player playback rate</a> &lt; 0 and <em>either</em>
        <var>player</var>'s:

        *   <a>current time</a> is <a>unresolved</a>, or
        *   <a>current time</a> &le; zero, or
        *   <a>current time</a> &gt; <a>source content end</a>,

    ::  set <var>player</var>'s <a>hold time</a> to <a>source content end</a>.
    :   If <a>player playback rate</a> = 0 and <var>player</var>'s
        <a>current time</a> is <a>unresolved</a>,
    ::  Set <var>player</var>'s <a>hold time</a> to zero.

    </div>

5.  If <var>player</var>'s <a>hold time</a> is <a>unresolved</a>, perform the
    following steps:

    1.  If <var>has pending ready promise</var> is true,
        <a title="resolve a Promise">resolve</a> <var>player</var>'s <a>current
        ready promise</a> with <var>player</var>.

    2.  Abort this procedure.

6.  Let <var>player</var>'s <a title="player start time">start time</a> be
    <a>unresolved</a>.

7.  If <var>has pending ready promise</var> is false,
    let <var>player</var>'s <a>current ready promise</a> be a new
    (pending) <a>Promise</a> object.

8.  Schedule a task to run as soon as <var>player</var> is <a>ready</a>.
    The task shall perform the following steps:

    1.  <a>Assert</a> that <a>hold time</a> is <a
        title="unresolved">resolved</a>. (This is because we don't queue this
        task if <a>hold time</a> is <a>unresolved</a> and anything that causes
        it to become <a>unresolved</a> while this task is queued, should cancel
        this task.)
    1.  Let <var>ready time</var> be the <a>time value</a> of
        the <a>timeline</a> associated with <var>player</var> at the moment
        when <var>player</var> became <a>ready</a>.
    2.  Let <var>new start time</var> be the result of evaluating
        <code><var>ready time</var> - <a>hold time</a> / <a>player
        playback rate</a></code> for <var>player</var>.
        If the <a>player playback rate</a> is zero, let <var>new start
        time</var> be simply <var>ready time</var>.
    3.  If <var>player</var>'s <a title="player playback rate">playback rate</a>
        is not 0, make <var>player</var>'s <a>hold time</a> <a>unresolved</a>.
    4.  Set the <a>player start time</a> of <var>player</var>
        to <var>new start time</var>.
    5.

        <div class="todo">Queue a task here for sampling custom effects.
        (This should happen before we resolve the ready promise.)
        </div>

    6.  <a title="resolve a Promise">Resolve</a> <var>player</var>'s <a>current
        ready promise</a> with <var>player</var>.
    7.  Run the procedure to <a>update a player's finished state</a>
        for <var>player</var>.

        <div class="annotation">
            Note that the order of the above two steps is important
            since it means that a player with zero-length <a>source
            content</a> will resolve its <a>current ready promise</a>
            before its <a>current finished promise</a>.
        </div>

        So long as the above task is scheduled but has yet to run,
        <var>player</var> is described as having a
        <dfn>pending play task</dfn>.

        A user agent MAY execute the above task immediately (if it
        determines <var>player</var> is immediately <a>ready</a>) thereby
        bypassing the <a>pending play state</a> altogether.

9.  Run the procedure to <a>update a player's finished state</a>
    for <var>player</var>.

<h4 id='pausing-a-player-section'>Pausing a player</h4>

Whenever a <a>player</a> has an <a>unresolved</a> <a title="player start
time">start time</a>, its <a>current time</a> will be suspended.

As with <a title="play a player">playing a player</a>, pausing may not happen
instantaneously (see <a href="#waiting-for-source-content" section></a>).
For example, if animation is performed by a separate process, it may
be necessary to synchronize the <a>current time</a> to ensure that it
reflects the state drawn by the animation process.

The procedure to <dfn>pause a player</dfn>, <var>player</var> is as follows:

1.  If <var>player</var> has a <a>pending pause task</a>, abort these steps.
1.  Let <var>has pending ready promise</var> be a boolean flag that is
    initially false.
1.  If <var>player</var> has a <a>pending play task</a>, cancel that task
    and let <var>has pending ready promise</var> be true.
1.  Set <var>player</var>'s <a>hold time</a> to <a>current time</a>.
1.  If <var>has pending ready promise</var> is false,
    set <var>player</var>'s <a>current ready promise</a> to a new
    (pending) <a>Promise</a> object.
1.  Schedule a task to be executed at the first possible moment after
    the user agent has performed any processing necessary to suspend
    the playback of any animations that are <a>inclusive
    descendants</a> of <var>player</var>'s <a>source content</a>, if any.
    The task shall perform the following steps:

    1.  Set <var>player</var>'s <a>hold time</a> to its <a>current time</a>
        (even if the current time is <a>unresolved</a>).
    1.  Make <var>player</var>'s <a title="player start time">start time</a>
        unresolved.

    1.

        <div class="todo">Queue a task here for sampling custom effects
            with the final current time.  (This should happen before we
            resolve the ready promise).
        </div>

    1.  <a title="resolve a Promise">Resolve</a> <var>player</var>'s <a>current
        ready promise</a> with <var>player</var>.
    1.  Run the procedure to <a>update a player's finished state</a>
        for <var>player</var>.

    So long as the above task is scheduled but has yet to run,
    <var>player</var> is described as having a <dfn>pending pause task</dfn>.
    While the task is running, however, <var>player</var> does
    <em>not</em> have a <a>pending pause task</a>.

1.  Run the procedure to <a>update a player's finished state</a>
    for <var>player</var>.

<h4 id="reaching-the-end">Reaching the end</h4>

<div class='informative-bg'>

<em>This section is non-normative</em>

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 <a
href="http://www.w3.org/TR/html5/embedded-content-0.html#media-elements">media
elements</a> [[HTML5]], the <a>current time</a> of Web Animations'
players do not play forwards beyond the <a>end time</a> of their
<a>source content</a> or play backwards past time zero.

A player that has reached the natural boundary of its playback range
is said to have <em>finished</em>.

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

<div class="figure">
  <img src="img/limiting.svg" width="500"
       alt="The effect of limiting the current time of a player.">
</div>
<p class="caption">
The effect of limiting the <a>current time</a> of a <a>player</a>
with a start time of 1s, a source content of length 3s, and
a positive <a>player playback rate</a>.
After the <a>current time</a> of the player reaches the end of the
source content, it is capped at 3s.
</p>

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

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

Similar behavior to the above scenario may arise when the
length of a player's <a>source content</a> changes.

Similarly, when the <a>player playback rate</a> is negative, the
<a>current time</a> does not progress past time zero.

</div>

<h4 id="the-current-finished-promise">The current finished promise</h4>

Each player has a <dfn>current finished promise</dfn>.
The <a>current finished promise</a> is initially a pending <a>Promise</a>
object.

The object is replaced with a new (pending) <a>Promise</a> object every time the
player leaves the <a>finished play state</a>.

<h4 id="updating-the-finished-state">Updating the finished state</h4>

For a player with a positive <a title="player playback rate">playback
rate</a>, the <a>current time</a> continues to increase until it
reaches the <a>source content end</a>.

The <dfn>source content end</dfn> of a player is equal to the <a>end
time</a> of the player's <a>source content</a>.
If the player has no <a>source content</a>, the <a>source content
end</a> is zero.

A player with a negative <a title="player playback rate">playback
rate</a>, the <a>current time</a> continues to decrease until it
reaches zero.

A player that has reached this boundary (or overshot it) and has a
<a title="unresolved">resolved</a> <a>player start time</a>
is said to be <a title="finished play state">finished</a>.
(If the player has an <a>unresolved</a> <a>player start time</a> it is
considered to be <a title="paused play state">paused</a> rather than
<a title="finished play state">finished</a>.)

The crossing of this boundary is checked on each modification to the
player object using the procedure for <a>update a player's finished
state</a> defined below.

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

<div class='todo'>
    Mention that this gets run at the end of each sample as well.
    And at the end of any update to the timing of the <a>source
    content</a>.
</div>

The procedure to <dfn>update a player's finished state</dfn> for
<var>player</var> is as follows:

1.  If both of the following conditions are true,

    *   <var>player</var>'s <a title="player start time">start time</a> is
        <a title="unresolved">resolved</a>, and
    *   <var>player</var> does <em>not</em> have a <a>pending play task</a> or
        a <a>pending pause task</a>,

    then update <var>player</var>'s <a>hold time</a> based on the first
    matching condition for <var>player</var> from below, if any:

    <div class='switch'>

    :   If <a>player playback rate</a> &gt; 0 and
        <a>current time</a> is <a title="unresolved">resolved</a> and
        greater than or equal to <a>source content end</a>,
    ::  let the <a>hold time</a> be the maximum value of
        <a>previous current time</a> and <a>source content end</a>.
        If the <a>previous current time</a> is
        <a>unresolved</a>, let the <a>hold time</a> be <a>source
        content end</a>.
    :   If <a>player playback rate</a> &lt; 0 and
        <a>current time</a> is <a title="unresolved">resolved</a> and
        less than or equal to 0,
    ::  let the <a>hold time</a> be zero.
    :   If <a>current time</a> is <a title="unresolved">resolved</a>, and
        <a>player playback rate</a> &ne; 0,
    ::  let the <a>hold time</a> be <a>unresolved</a>.

    </div>

1.  Let <var>current finished state</var> be true if the <a>play
    state</a> of <var>player</var> is finished. Otherwise, let it be
    false.
1.  If <var>current finished state</var> is true and <a>previous
    finished state</a> is false,
    <a title="resolve a promise">resolve</a> <var>player</var>'s <a>current
    finished promise</a> object with <var>player</var>.
1.  If <var>current finished state</var> is false and <a>previous
    finished state</a> is true,
    set <var>player</var>'s <a>current finished promise</a> to a new (pending)
    Promise object.
1.  Set <var>player</var>'s <a>previous finished state</a> to
    <var>current finished state</var>.
1.  Set the <a>previous current time</a> of <var>player</var> be the
    result of calculating its <a>current time</a>.

<h4 id="finishing-a-player-section">Finishing a player</h4>

A player can be advanced to the natural end of its current playback
direction by using the procedure to <dfn>finish a player</dfn>
for <var>player</var> defined below:


1.  If <a>player playback rate</a> is zero,
    or if <a>player playback rate</a> &gt; 0 and <a>source content end</a> is
    infinity,
    <a href="http://heycam.github.io/webidl/#dfn-throw">throw</a> an
    InvalidStateError and abort these steps.

2.  Set <var>limit</var> as follows:

    <div class="switch">

    :   If <a>player playback rate</a> &gt; 0,</dt>
    ::  Let <var>limit</var> be <a>source content end</a>.</dd>

    :   Otherwise,
    ::  Let <var>limit</var> be zero.</dd>

    </div>

3.  <a>Set the current time</a> to <var>limit</var>.

    <div class="annotation">
        The procedure for setting the current time has the side effect of
        cancelling any <a>pending pause task</a> so we don't need to
        handle that here.
    </div>

4.  If there is a <a>pending play task</a>, cancel that task and
    <a title="resolve a Promise">resolve</a> the <a>current ready promise</a> of
    <var>player</var> with <var>player</var>.

6.  Run the procedure to <a>update a player's finished state</a>
    for <var>player</var>.

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

<h4 id='cancelling-a-player-section'>Cancelling a player</h4>

 A player can be cancelled which causes the <a>current time</a> to
become <a>unresolved</a> hence removing any effects caused by the
<a>source content</a>.

The procedure to <dfn>cancel a player</dfn> for <var>player</var> is
as follows:

1.  Run the procedure to <a>reset a player's pending tasks</a> on
    <var>player</var>.
2.  <a title="reject a Promise">Reject</a> the <a>current finished promise</a>
    with a DOMException named "AbortError".
3.  Let <a>current finished promise</a> be a new (pending) <a>Promise</a>
    object.
4.  Make <var>player</var>'s <a>hold time</a> <a>unresolved</a>.
5.  Make <var>player</var>'s <a title="player start time">start time</a>
    <a>unresolved</a>.
7.  Queue a task to call any <a>custom effects</a> associated with
    <a>inclusive descendants</a> of <var>player</var>'s <a>source content</a>
    with an <a>unresolved</a> time fraction.
    <p class="issue">
      The procedures for calling custom effects needs to be reworked.
      Currently they probably involve calling too often for changes that could
      be coalesced.
    </p>

<h4 id="speed-control">Speed control</h4>

<div class="informative-bg">

The rate of play of a player can be controlled by setting its
<em>playback rate</em>.
For example, setting a playback rate of 2 will cause the player's
<a>current time</a> to increase at twice the rate of its <a>timeline</a>.
Similarly, a playback rate of -1 will cause the player's <a>current
time</a> to decrease at the same rate as the <a>time values</a> from
its <a>timeline</a> increase.

Note that <a>animation nodes</a> also have a <a
title="animation node playback rate">playback rate</a> associated
with them that behaves differently to that defined here.

</div>

<a>Players</a> have a <dfn title="player playback
rate">playback rate</dfn> that provides a scaling factor from the rate
of change of the associated <a>timeline</a>'s <a>time values</a> to
the player's <a>current time</a>.
The <a title="player playback rate">playback rate</a> is initially 1.

Setting a player's <a title="player playback rate">playback rate</a>
to zero effectively pauses the player (however, the <a>play state</a>
does not necessarily become <a title="paused play state">paused</a>).

<h5 id="updating-the-playback-rate-of-a-player">
Updating the playback rate of a player</h5>

Changes to the <a title="player playback rate">playback rate</a>
trigger a compensatory seek so that that the player's
<a>current time</a> is unaffected by the change to the playback
rate.

The procedure to <dfn>update the player playback rate</dfn> of
a <a>player</a>, <var>player</var> to <var>new playback rate</var>
is as follows:

1.  Let <var>previous time</var> be the value of the
    <a>current time</a> of <var>player</var> before changing the
    <a title="player playback rate">playback rate</a>.
2.  Set the <a title="player playback rate">playback rate</a> to
    <var>new playback rate</var>.
3.  If <var>previous time</var> is <a title="unresolved">resolved</a>,
    <a>set the current time</a> of <var>player</var> to
    <var>previous time</var>.

The procedure to <dfn>silently update the player playback rate</dfn>
of <a>player</a>, <var>player</var> to <var>new playback rate</var>
is identical to the above procedure except that rather than invoking
the procedure to <a>set the current time</a> in the final step, the
procedure to <a>silently set the current time</a> is invoked instead.

<h4 id="reversing-a-player-section">Reversing a player</h4>

The procedure to <dfn>reverse a player</dfn> of <a>player</a>
<var>player</var> is as follows:

1.  If there is no <a>timeline</a> associated with <var>player</var>, or the
    associated <a>timeline</a> is <a title="inactive timeline">inactive</a>
    <a href="http://heycam.github.io/webidl/#dfn-throw">throw</a> an
    InvalidStateError and abort these steps.
2.  <a>Silently update the player playback rate</a> of
    <var>player</var> to <code>&minus;<a>player playback rate</a></code>.

    <div class="annotation">
        This must be done silently or else we may end up resolving
        the <a>current ready promise</a> when we do the compensatory
        seek despite the fact that we are most likely not exiting the
        <a>pending play state</a>.
    </div>
3.  Run the steps to <a>play a player</a> for <var>player</var>.

<h4 id="player-state">Player state</h4>

A <a>player</a> may be described as being in one of the following
<dfn title="play state">play states</dfn> for each of which, a 
non-normative description is also provided:

<div class=informative-bg>

:   <dfn title="idle play state">idle</dfn>
::  The <a>current time</a> of the player is <a>unresolved</a> and
    there are no pending tasks.
    In this state the player has no effect.
:   <dfn title="pending play state">pending</dfn>
::  The player is waiting on some pending task to complete.
:   <dfn title="running play state">running</dfn>
::  The player has a resolved <a>current time</a> that changes on each
    <a>sample</a> (provided the <a>player playback rate</a> is not zero).
:   <dfn title="paused play state">paused</dfn>
::  The player has been suspended and the <a>current time</a>
    is no longer changing.
:   <dfn title="finished play state">finished</dfn>
::  The player has reached the natural boundary of its playback range
    and the <a>current time</a> is no longer updating.

</div>

The <a>play state</a> of <a>player</a>, <var>player</var>, at a given
moment is the state corresponding to the <em>first</em> matching
condition from the following:

<div class="switch">

:   <var>player</var> has a <a>pending play task</a> or a
    <a>pending pause task</a>,
::  &rarr; <a title="pending play state">pending</a>
:   The <a>current time</a> of <var>player</var> is
    <a>unresolved</a>,
::  &rarr; <a title="idle play state">idle</a>
:   The <a title="player start time">start time</a> of <var>player</var> is
    <a>unresolved</a>,
::  &rarr; <a title="paused play state">paused</a>
:   For <var>player</var>,
    <a>player playback rate</a> &gt; 0 and
    <a>current time</a> &ge; <a>source content end</a>; or<br>
    <a>player playback rate</a> &lt; 0 and
    <a>current time</a> &le; 0,
::  &rarr; <a title="finished play state">finished</a>
:   Otherwise,
::  &rarr; <a title="running play state">running</a>

</div>

<div class="note">

Note that the <a>paused play state</a> effectively
&ldquo;wins&rdquo; over the <a>finished play state</a>.

However, a player that is paused outside of its natural playback range can
be converted from a <a title="paused play state">paused</a>
player into a <a title="finished play state">finished</a> player
without restarting by setting the <a>player start time</a> such as below:

<pre class='example sh_javascript'>
player.source.timing.duration = 5000;
player.currentTime = 4000;
player.pause();
player.ready.then(function() {
  player.source.timing.duration = 3000;
  alert(player.playState); // Displays 'paused'
  player.startTime =
    document.timeline.currentTime - player.currentTime * player.playbackRate;
  alert(player.playState); // Displays 'finished'
});
</pre>

</div>

<h3 id="animation-nodes">Animation nodes</h3>

An <dfn>animation node</dfn> is an abstract term referring to an item in
the timing hierarchy.

<h4 id="animation-nodes-and-players">Relationship between animation nodes and players</h4>

The <a>source content</a> of a <a>player</a>, if set, is a type of
<a>animation node</a>.
The <a>source content</a> of a <a>player</a> is said to be <dfn
title="directly associated with a player">directly associated</dfn>
with that player.

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

An <a>animation node</a> is <dfn>associated with a player</dfn> if it
is <a>directly associated with a player</a> or if it has an
<a>ancestor</a> <a>animation group</a> that is <a>directly associated
with a player</a>.
At a given moment, an <a>animation node</a> can be <a
title="associated with a player">associated</a> with at most one
<a>player</a>.

An <a>animation node</a>, <var>node</var>, is <dfn>associated with
a timeline</dfn>, <var>timeline</var>, if <var>node</var> is
<a>associated with a player</a> which, in turn, is associated with
<var>timeline</var>.

<h4 id="types-of-animation-nodes">Types of animation nodes</h4>

This specification defines two types of <a>animation nodes</a>:

* <a>animations</a>, and
* <a>animation groups</a>.

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

<h4 id="the-active-interval">The active interval</h4>

<div class="informative-bg">

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

The lower bound of the <a>active interval</a> is determined by the
<a title="animation node start time">start time</a> of the
<a>animation node</a> but may be shifted by a <a>start delay</a> on
the <a>animation node</a>.

The upper bound of the interval is determined by the <a>active
duration</a>.

The relationship between the <a
title="animation node start time">start time</a>, <a>start
delay</a>, and <a>active duration</a> is illustrated below.

<div class="figure">
<img src="img/active-interval-examples.svg" width="600"
    alt="Examples of the effect of the start delay on the endpoints
        of the active interval">
</div>
<p class="caption">
Examples of the effect of the <a>start delay</a> on the endpoints of
the <a>active interval</a>.<br>
(a) An animation node with no delay; the <a
title="animation node start time">start time</a> and beginning of
the <a>active interval</a> are coincident.<br>
(b) An animation node with a positive delay; the beginning of the
<a>active interval</a> is deferred by the delay.<br>
(c) An animation node with a negative delay; the beginning of the
<a>active interval</a> is brought forward by the delay.
</p>

An <a>end delay</a> may also be specified but is primarily only of
use when sequencing animations such as by using an
<a>animation sequence</a>.

</div>

<a>Animation nodes</a> define an <dfn>active interval</dfn> which is
the period of time during which the node is scheduled to produce its
effect with the exception of <a>fill modes</a> which apply outside the
<a>active interval</a>.

The lower bound of the <a>active interval</a> is defined by the
combination of the animation node's
<a title="animation node start time">start time</a> and <a>start delay</a>.

An <a>animation node</a>'s
<dfn title="animation node start time">start time</dfn> is the moment at
which the <a>parent animation group</a>,
if any, has scheduled the <a>animation node</a> to begin.
It is expressed in <a>inherited time</a>.
In most cases, including the case when the <a>animation node</a> has
no <a>parent animation group</a>,
the <a title="animation node start time">start time</a> is zero.
The singular exception is <a>animation sequence</a> which set
the <a title="animation node start time">start times</a> of their
children as described in <a
href="#the-start-time-of-children-of-an-animation-sequence" section></a>.

In addition to the <a title="animation node start time">start
time</a>, an <a>animation node</a> also has a <dfn>start delay</dfn>
which is an offset from the <a
title="animation node start time">start time</a>.
Unlike the <a title="animation node start time">start time</a> which
is determined by the <a>parent animation group</a>, the <a>start
delay</a> is a property of the <a>animation node</a> itself.

The lower bound of the <a>active interval</a> of an <a>animation
node</a>, expressed in <a title="inherited time">inherited time
space</a>, is the sum of the <a
title="animation node start time">start time</a> and the <a>start
delay</a>.

These definitions are incorporated in the calculation of the <a>local
time</a> (see <a href="#local-time-and-inherited-time" section></a>)
and <a>active time</a>.

The length of the <a>active interval</a> is called the <dfn>active
duration</dfn>, the calculation of which is defined in <a
href="#calculating-the-active-duration" section></a>.

Similar to the <a>start delay</a>, an <a>animation node</a> also has
an <dfn>end delay</dfn> which may be used to delay the <a
title="animation node start time">start time</a> of the <a>next
sibling</a> in a <a>animation sequence</a>.

<h4 id="local-time-and-inherited-time">Local time and inherited time</h4>

<div class="informative-bg">

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

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.
<a>Animation groups</a> typically perform some
transformations on the <a>time values</a> they
receive from their <a title="parent animation group">parent</a> or
<a>player</a> before passing on the transformed <a>time values</a>
to their children.
Child <a>animation nodes</a> then operate <em>within</em> that
transformed time space.

Children take the transformed time values from their
parent&mdash;called the <a>inherited time</a>&mdash;and add their
<a title="animation node start time">start time</a> to establish
their own <a title="local time">local time space</a> as illustrated
below.

<div class="figure">
<img src="img/local-time.svg" width="600"
    alt="Inherited time and local time.">
</div>
<p class="caption">
Inherited time and local time.<br>
At time <var>t</var>, the <a>inherited time</a> is 2.5.<br>
For <a>animation node</a> (a) which has a <a
  title="animation node start time">start time</a> of 1, the
  <a>local time</a> is 1.5.<br>
For <a>animation node</a> (b) which has a <a
  title="animation node start time">start time</a> of 1
  and a <a>start delay</a> of 1,
  the <a>local time</a> is also 1.5
  since <a>local time</a> is based on an <a>animation node</a>'s
  <a title="animation node start time">start time</a> only,
  and not on its <a>start delay</a>.
</p>

</div>

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

<div class='switch'>

:   If the <a>animation node</a> has a <a>parent animation
    group</a>,
::  the inherited time is the <a>parent animation group</a>'s current
    <a>transformed time</a>.
:   If the <a>animation node</a> is directly associated with
    a <a>player</a>,
::  the inherited time is the <a>current time</a> of the
    <a>player</a>.
:   Otherwise,
::  the inherited time is <a>unresolved</a>.

</div>

The <dfn>local time</dfn> of an <a>animation node</a> is the
<a>animation node</a>'s <a>inherited time</a> minus its <a
title="animation node start time">start time</a>.
If the <a>inherited time</a> is <a>unresolved</a> then the local time
is also <a>unresolved</a>.

<h4 id="animation-node-phases-and-states">Animation node phases and states</h4>

<div class="informative-bg"><em>This section is non-normative</em>

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

The different phases are illustrated below.

<div class="figure">
<img src="img/animation-node-phases-and-states.svg" width="700"
    alt="An example of the different phases and states used to
         describe an animation node.">
</div>
<p class="caption">
An example of the different phases and states used to describe
an <a>animation node</a>.
</p>

The phases are as follows:

:   <a>before phase</a>
::  The <a>animation node</a>'s <a>local time</a> falls before the
    node's <a>active interval</a>.
:   <a>active phase</a>
::  The <a>animation node</a>'s <a>local time</a> falls inside the
    node's <a>active interval</a>.
:   <a>after phase</a>
::  The <a>animation node</a>'s <a>local time</a> falls after the
    node's <a>active interval</a>.

In addition to these phases, an <a>animation node</a> may also be
described as being in one of several overlapping <em>states</em>.
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:

:   <a>in play</a>
::  Corresponds to an <a>animation node</a> whose <a>active time</a>
    is changing on each sample.
    This occurs when the <a>animation node</a> <em>and all its
    ancestors</em> are in the <a>active phase</a>.
    <a>Animations</a> only &ldquo;move&rdquo; when
    they are <a>in play</a>.

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

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

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

The normative definition of each of these states follows.

</div>

An <a>animation node</a> is in the <dfn>before phase</dfn> if the
animation node's <a>local time</a> is not <a>unresolved</a> and is
less than the node's <a>start delay</a>.

An <a>animation node</a> is in the <dfn>active phase</dfn> if
<em>all</em> of the following conditions are met:

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

An <a>animation node</a> is in the <dfn>after phase</dfn> if the
animation node's <a>local time</a> is not <a>unresolved</a> and is
<em>greater than or equal</em> to the sum of its <a>start delay</a>
and <a>active duration</a>.

An <a>animation node</a> is <dfn>in play</dfn> if <em>all</em>
of the following conditions are met:

1.  the <a>animation node</a> is in the <a>active phase</a>, and
2.  the <a>animation node</a> has a <a>parent animation group</a> that
    is <a>in play</a> or else the <a>animation node</a> is <a>directly
    associated with a player</a> that is not <a
    title="finished play state">finished</a>.

An animation node is <dfn>current</dfn> if it <em>any</em> of the
following conditions is true:

*   it is in the <a>before phase</a>, or
*   it is <a>in play</a>, or
*   it has a <a>parent animation group</a> and the
    <a>parent animation group</a> is <a>current</a>.

An animation node is <dfn>in effect</dfn> if its <a>active time</a> as
calculated according to the procedure in <a
href="#calculating-the-active-time" section></a> is not
<a>unresolved</a>.

<h3 id="fill-behavior">Fill behavior</h3>

The effect of an <a>animation node</a> when it is not <a>in play</a> is
determined by its <dfn>fill mode</dfn>.

The possible <a>fill modes</a> are:

*   none,
*   forwards,
*   backwards, and
*   both.

The normative definition of these modes is incorporated in the
calculation of the <a>active time</a> in <a
href="#calculating-the-active-time" section></a>.

<h4 id="fill-modes">Fill modes</h4>

<div class='informative-bg'><em>This section is non-normative</em>

The effect of each <a>fill mode</a> is as follows:

:   none
::  The animation node has no effect when it is not <a>in play</a>.
:   forwards</dt>
::  When the animation node is in the <a>after phase</a>,
    or when the animation node is in the <a>active phase</a> but an
    <a>ancestor</a> is in its <a>after phase</a>,
    the animation node will produce the same <a
    title="transformed time">transformed time value</a> as the last
    moment it is scheduled to be <a>in play</a>.

    For all other times that the animation node is not <a>in play</a>,
    it will have no effect.
:   backwards
::  When the animation node is in the <a>before phase</a>,
    or when the animation node is in the <a>active phase</a> but an
    <a>ancestor</a> is in its <a>before phase</a>,
    the animation node will produce the same <a
    title="transformed time">transformed time value</a> as the earliest
    moment that it is scheduled to be <a>in play</a>.

    For all other times that the animation node is not <a>in play</a>,
    it will have no effect.
:   both</dt>
::  When the animation node or an <a>ancestor</a> is in its <a>before
    phase</a>, <span class="prop-value">backwards</span> fill behavior
    is used.

    When the animation node or an <a>ancestor</a> is in its <a>after
    phase</a>, <span class="prop-value">forwards</span> fill behavior is
    used.

Some examples of the these fill modes are illustrated below.

<div class="figure">
  <img src="img/animation-state-and-fill-behavior.svg" width="600"
    alt="Examples of various fill modes and the states produced.">
</div>
<p class="caption">
  Examples of various fill modes and the states produced.<br>
  (a) fill mode &lsquo;none&rsquo;. The animation node has no effect
      outside its active interval.<br>
  (b) fill mode &lsquo;forwards&rsquo;. After the active interval has
      finished, the timed value continues to maintain a fill value.<br>
  (c) fill mode &lsquo;backwards&rsquo;. The animation node produces
      a fill value until the start of the active interval.<br>
  (d) fill mode &lsquo;both&rsquo;. Both before and after the active
      interval the animation node produces a fill value.
</p>

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

<div class="issue">
Currently <a>timing functions</a> that generate results outside the
range [0, 1] will behave unexpectedly when applied to animation
groups, as children will increase iterations or enter into fill mode
rather than continuing to extrapolate along their defined behavior
(which is what they would do if the timing function applied to them
directly).

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

See <a
href='http://lists.w3.org/Archives/Public/public-fx/2013AprJun/0184.html'>section
15 (Overflowing fill) of minuted discussion from Tokyo 2013 F2F</a>.
</div>

</div>

<h3 id="repeating">Repeating</h3>

<h4 id="iteration-intervals">Iteration intervals</h4>

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

Unlike the <a>active interval</a>, an animation node can have multiple
<a>iteration intervals</a> although typically only the interval
corresponding to the <a>current iteration</a> is of interest.

The length of a single iteration is called the <dfn>iteration
duration</dfn>.
The initial <a>iteration duration</a> of an animation node is simply
its <a>intrinsic iteration duration</a>.

The <dfn>intrinsic iteration duration</dfn> of an animation node is
zero, however some specific types of animation node such as
<a>animation groups</a> override this behavior and provide an
alternative intrinsic duration (see <a
href="#the-intrinsic-iteration-duration-of-an-animation-group"
section></a> and <a
href="#the-intrinsic-iteration-duration-of-an-animation-sequence"
section></a>).

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

<div class="informative-bg"><em>This section is non-normative</em>

Comparing the <a>iteration duration</a> and the <a>active
duration</a> 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 <a>iteration duration</a>.

The relationship between the <a>iteration duration</a> and <a>active
duration</a> is illustrated below.

<div class="figure">
  <img src="img/iteration-intervals.svg" width="600"
      alt="Comparison of the iteration duration and active time.">
</div>
<p class="caption">
  A comparison of the <a>iteration duration</a> and <a>active
  duration</a> of an animation node with an <a>iteration count</a> of
  2.5.
  Note that the <a>iteration duration</a> for the final iteration does
  not change, it is simply cut-off by the <a>active duration</a>.
</p>

</div>

<h4 id="controlling-iteration">Controlling iteration</h4>

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

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

The behavior of these parameters is defined in the calculations in <a
href="#core-animation-node-calculations" section></a>.

<div class="informative-bg"><em>This section is non-normative</em>

The effect of the <a>iteration count</a> and <a>iteration start</a>
parameters is illustrated below.

<div class="figure">
  <img src="img/iteration-count-and-start.svg" width="600"
    alt="The effect of the iteration count and iteration start parameters">
</div>
<p class="caption">
  The effect of the <a>iteration count</a> and <a>iteration start</a>
  parameters.<br>
  In the first case the <a>iteration count</a> is 2.5 resulting in the
  third iteration being cut-off half way through its <a>iteration
  interval</a>.<br>
  The second case is the same but with an <a>iteration start</a> of
  0.5.
  This causes the <a>animation node</a> to begin half way through the
  first iteration.
</p>

Unlike the <a>iteration count</a> parameter, the <a>iteration
start</a> parameter does not effect the length of the <a>active
duration</a>.

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

</div>

<h4 id="iteration-time-space">Iteration time space</h4>

<div class="informative-bg"><em>This section is non-normative</em>

We have already encountered different time spaces in describing
<a>local time</a> and <a>inherited time</a> (see <a
href="#local-time-and-inherited-time" section></a>).
Repetition introduces yet another time space: the iteration time
space.


<em>Iteration time space</em> is a time space whose zero time is the
beginning of an animation node's current iteration.


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


These time spaces are illustrated below.

<div class="figure">
  <img src="img/time-spaces.svg" width="600"
    alt="A comparison of local time, active time, and iteration time.">
</div>
<p class="caption">
A comparison of local time, active time, and iteration time for an
animation with a iteration duration of 1s and an iteration count of
2.5.
</p>

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

In addition to these time spaces we can also refer to the
<em>document time space</em> which is time space of the <a>time
values</a> of the <a>document timeline</a> of the <a
href="http://www.w3.org/TR/html5/browsers.html#active-document">active
document</a>.

</div>

<h4 id="interval-timing">Interval timing</h4>

<div class="informative-bg"><em>This section is non-normative</em>

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


In the examples below, for the repeated node, at local time 1s,
the iteration time is 0.
For the sequenced nodes, at inherited time 1s, only node B will be
<a>in play</a>; there is no overlap.

<div class="figure">
  <img src="img/endpoint-exclusive-timing.svg" width="600"
    alt="Illustration of end-point exclusive timing.">
</div>
<p class="caption">
  Illustration of end-point exclusive timing. For both repeated and
  sequenced animation nodes there is no overlap at the boundaries
  between intervals.
</p>

An exception to this behavior is that when performing a <a
href="#fill-behavior">fill</a>, if the fill begins at an
interval endpoint, the endpoint is used.
This behavior falls out of the algorithm given in <a
href="#calculating-the-iteration-time"
section></a> and is illustrated below.

<div class="figure">
  <img src="img/endpoint-exclusive-timing-and-fill.svg" width="600"
    alt="Effect of iterations and fill on iteration time.">
</div>
<p class="caption">
  After one iteration, the iteration time is 0, but after two iterations
  (and thereonwards), the iteration time is equal to the iteration
  duration due to the special behavior defined when an animation node
  fills.
</p>

</div>

<h3 id="animation-node-speed-control">Animation node speed control</h3>

Like <a>players</a>, <a>animation nodes</a> also have a <dfn
title="animation node playback rate">playback rate</dfn> parameter.
The <a title="animation node playback rate">playback rate</a> of
an <a>animation node</a> is a finite real number that acts as
a multiplier when calculating the <a>animation node</a>'s <a>transformed
time</a> from its <a>local time</a>.

The effect of setting the <a title="animation node playback
rate">playback rate</a> of an <a>animation node</a> differs from the
setting the <a title="player playback rate">playback rate</a> on
a player.  Its behavior is defined in the timing calculations given in
<a href="#core-animation-node-calculations" section></a>.

<div class="informative-bg"><em>This section is non-normative</em>

In summary, the behavior of the <a title="animation node playback
rate">playback rate</a> of an <a>animation node</a> is as follows:

*   The <a title="animation node playback rate">playback rate</a> is
    applied only to the <a>active interval</a> of an <a>animation
    node</a> and not to the time while it is <a
    title="start delay">delayed</a> or <a title="fill mode">filling</a>.

*   Setting a negative <a title="animation node playback rate">playback
    rate</a> on an <a>animation node</a> causes the <a>animation
    node</a> to begin at the end of its <a>active interval</a>.
    This differs from the <a title="player playback rate">playback
    rate</a> on a <a>player</a>.
    Setting a <a title="player playback rate">playback rate</a> on
    a <a>player</a> to a negative value at a moment before the
    <a>player</a>'s </a>source content</a> has begun, will result in the
    <a>source content</a> never playing.

*   Setting the <a title="animation node playback rate">playback
    rate</a> of an <a>animation node</a> affects the calculated value of
    the <a>active duration</a> (see <a
    href="#calculating-the-active-duration"
    section></a>).

*   Changing the <a title="animation node playback rate">playback
    rate</a> of an <a>animation node</a> whose <a>local time</a> is
    within its <a>active interval</a> will cause it to jump.
    This is because the <a>active duration</a> will be updated but the
    <a>local time</a> will not.

    Furthermore, if other <a>animation nodes</a> depend on the
    <a>animation node</a>'s <a>active duration</a>, such as sibling
    <a>animation node</a> in a <a>animation sequence</a>, they
    too may jump as a result of setting the <a>animation node</a>'s <a
    title="animation node playback rate">playback rate</a>.

    For runtime speed control the <a
    title="player playback rate">playback rate</a> of the
    <a>player</a> should be used.

</div>

<h3 id="core-animation-node-calculations">Core animation node calculations</h3>

<h4 id="overview">Overview</h4>

<div class="informative-bg"><em>This section is non-normative</em>

At the core of the Web Animations timing model is the process that
takes an <a>inherited time</a> value and converts it to an
<a>iteration time</a>.


Following this, further transformations are applied before resulting at
a final <a>transformed time</a>.


The first step in this process is to calculate the bounds of the
<a>active interval</a> which is determined by the <a>active
duration</a>.

This process is illustrated below.

<div class="figure">
  <img src="img/active-duration-calculation.svg" width="650"
    alt="Calculation of the active duration.">
</div>
<p class="caption">
  Calculation of the <a>active duration</a> is based on
  multiplying the <a>iteration duration</a> by the <a>iteration
  count</a> and then dividing by the <a
  title="animation node playback rate">playback rate</a>.
</p>
<p>
  The process for calculating the <a>active duration</a> is normatively
  defined in <a href="#calculating-the-active-duration"
  section></a>.
</p>
<p>
  Having established the <a>active duration</a>, the process for
  transforming an <a>animation node</a>'s <a>inherited time</a> into its
  <a>transformed time</a> is illustrated below.
</p>
<div class="figure">
  <img src="img/time-calculations.svg" width="650"
    alt="An overview of timing model calculations.">
</div>
<p class="caption">
  An overview of timing model calculations.<br>
  (1) The <a>inherited time</a> is converted into a <a>local time</a> by
  incorporating the <a title="animation node start time">start
  time</a>.<br>
  (2) The <a>local time</a> is converted into an <a>active time</a> by
  incorporating the <a>start delay</a>.<br>
  (3) The <a title="animation node playback rate">playback rate</a>
  and <a>iteration start</a> properties are
  applied to the <a>active time</a> to produce the <a>scaled active
  time</a>.<br>
  (4) The <a>scaled active time</a> is then converted to an offset
  within a single iteration: the <a>iteration time</a>.<br>
  (5) The <a>iteration time</a> is converted into a <a>directed time</a>
  by incorporating the <a>playback direction</a>.<br>
  (6) Finally, a timing function is applied to the <a>directed
  time</a> to produce the <a>transformed time</a>.
</p>

The first step, calculating the <a>local time</a> is described in <a
href="#local-time-and-inherited-time" section></a>.
Steps 2 to 4 in the diagram are described in the following sections.
Steps 5 and 6 are described in
<a href="#calculating-the-directed-time" section></a>
and
<a href="#calculating-the-transformed-time" section></a>
respectively.

</div>


<h4 id="calculating-the-active-duration">Calculating the active duration</h4>

In order to calculate the <a>active duration</a> we first define the
<a>repeated duration</a> as follows:

<blockquote>
  <dfn>repeated duration</dfn> =
    <code><a>iteration duration</a> &times;
          <a>iteration count</a></code>
    <p>
      If either the <a>iteration duration</a> or <a>iteration count</a>
      are zero, the <a>repeated duration</a> is zero.
    </p>
    <p class="note">
      This clarification is needed since the result of infinity
      multiplied by zero is undefined according to IEEE 754-2008.
    </p>
</blockquote>

The <a>active duration</a> is calculated according to the following
steps:

1.  If the <a title="animation node playback rate">playback rate</a> is
      zero, return <code>Infinity</code>.
2.  Otherwise, return <code><a>repeated duration</a> / abs(<a
      title="animation node playback rate">playback rate</a>)</code>.

<h4 id="transforming-the-local-time">Transforming the local time</h4>

<h5 id="calculating-the-active-time">Calculating the active time</h5>

The <dfn>active time</dfn> is based on the <a>local time</a>
and <a>start delay</a>.
However, it is only defined when the <a>animation node</a> should
produce an output and hence depends on its <a>fill mode</a> and
phase as well as the phase of its <a>parent animation group</a>, if
any, as follows,

<div class="switch">

:   If the animation node is in the <a>before phase</a>,
::  The result depends on the first matching condition from the
    following,

    <div class="switch">

    :   If the animation node has a <a>parent animation group</a>
        and that parent animation group is in the <a>after
        phase</a>,
    ::  Return an <a>unresolved</a> <a>time value</a>.
    :   If the <a>fill mode</a> is <span
        class="prop-mode">backwards</span> or <span
        class="prop-mode">both</span>,
    ::  Return zero.
    :   Otherwise,
    ::  Return an <a>unresolved</a> <a>time value</a>.

    </div>

:   If the animation node is in the <a>active phase</a>,
::  The result depends on the first matching condition from the
    following,

    <div class="switch">

    :   If the animation node has a <a>parent animation group</a>
        and that parent animation group is in the <a>before
        phase</a>, and the <a>fill mode</a> of this animation node
        is <span class="prop-value">none</span> or <span
        class="prop-value">forwards</a>,
    ::  Return an <a>unresolved</a> <a>time value</a>.
    :   If the animation node has a <a>parent animation group</a>
        and that parent animation group is in the <a>after
        phase</a>, and the <a>fill mode</a> of this animation node
        is <span class="prop-value">none</span> or <span
        class="prop-value">backwards</a>,
    ::  Return an <a>unresolved</a> <a>time value</a>.
    :   Otherwise,
    ::  Return <code><a>local time</a> - <a>start delay</a></code>.

    </div>

:   If the animation node is in the <a>after phase</a>,
::  The result depends on the first matching condition from the
    following,

    <div class="switch">

    :   If the animation node has a <a>parent animation group</a>
        and that parent animation group is in the <a>before
        phase</a>,
    ::  Return an <a>unresolved</a> <a>time value</a>.
    :   If the <a>fill mode</a> is <span
        class="prop-mode">forwards</span> or <span
        class="prop-mode">both</span>,
    ::  Return the <a>active duration</a>.
    :   Otherwise,
    ::  Return an <a>unresolved</a> <a>time value</a>.

    </div>

:   Otherwise (the <a>local time</a> is <a>unresolved</a>),
::  Return an <a>unresolved</a> <a>time value</a>.

</div>

<h5 id="calculating-the-scaled-active-time">Calculating the scaled active time</h5>

Before the <a>active time</a> can be converted to an <a>iteration
time</a> we must factor in the <a>animation node</a>'s <a
title="animation node playback rate">playback rate</a> and
<a>iteration start</a>.
The result is called the <a>scaled active time</a>.

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

<blockquote>
  <dfn>start offset</dfn> =
    <code><a>iteration start</a> &times;
          <a>iteration duration</a></code>

  If the <a>iteration start</a> is zero, the <a>start offset</a>
  is zero.

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

</blockquote>

The <dfn>scaled active time</dfn> is calculated according to
the following steps:

1.  If the <a>active time</a> is <a>unresolved</a>, return
    an <a>unresolved</a> <a>time value</a>.

2.  Return the scaled active time based on the
    <a title="animation node playback rate">playback rate</a> as
    follows,

    <div class="switch">

    :   If the <a title="animation node playback rate">playback
        rate</a> is less than zero,
    ::  Return <code>(<a>active time</a> -
                    <a>active duration</a>)
        &times; <a title="animation node playback rate">playback
        rate</a> + <a>start offset</a></code>.

    :   If the <a title="animation node playback rate">playback
        rate</a> is zero,
    ::  Return <a>start offset</a>.

    :   Otherwise,
    ::  Return <code><a>active time</a>
        &times; <a title="animation node playback rate">playback
        rate</a> + <a>start offset</a></code>.

    </div>

<h5 id="calculating-the-iteration-time">Calculating the iteration time</h5>

The <dfn>iteration time</dfn> is calculated according to the
following steps:

1.  If the <a>scaled active time</a> is <a>unresolved</a>,
    return <a>unresolved</a>.

2.  If the <a>iteration duration</a> is zero, return zero.

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

4.  Otherwise, return <code><a>scaled active time</a>
    % <a>iteration duration</a></code>.

<h4 id="calculating-the-current-iteration">Calculating the current iteration</h4>

The <dfn>current iteration</dfn> can be calculated using the
following steps:

1.  If the <a>scaled active time</a> is <a>unresolved</a>, return
    <a>unresolved</a>.

2.  If the <a>scaled active time</a> is zero, return zero.

3.  If the <a>iteration duration</a> is zero, return
    <code>ceil(<a>iteration start</a> + <a>iteration count</a>) -
    1</code>.

4.  If the <a>iteration time</a> equals the <a>iteration
    duration</a>, return <code><a>iteration start</a>
    + <a>iteration count</a> - 1</code>.

5.  Return <code>floor(<a>scaled active time</a> /
    <a>iteration duration</a>)</code>.
    <p class="note">
      If the <a>iteration duration</a> is infinite, the
      result of <code>floor(<a>scaled active time</a> /
      <a>iteration duration</a>)</code> will be zero as defined by
      IEEE 754-2008.

<h3 id="direction-control">Direction control</h3>

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

*   normal,
*   reverse,
*   alternate, or
*   alternate-reverse.

The semantics of these values are incorporated into the calculation of
the <a>directed time</a> which follows.

<div class="informative-bg"><em>This section is non-normative</em>

A non-normative definition of these values is as follows:

:   normal
::  All iterations are played as specified.

:   reverse
::  All iterations are played in the reverse direction from the way
    they are specified.

:   alternate
::  Even iterations are played as specified, odd iterations are played
    in the reverse direction from the way they are specified.

:   alternate-reverse
::  Even iterations are played in the reverse direction from the way
    they are specified, odd iterations are played as specified.

</div>

<h4 id="calculating-the-directed-time">Calculating the directed time</h4>

  The <dfn>directed time</dfn> is calculated from the <a>iteration
  time</a> using the following steps:

1.  If the <a>iteration time</a> is <a>unresolved</a>, return
    <a>unresolved</a>.

2.  Calculate the <var>current direction</var> using the first
    matching condition from the following list:
    <div class="switch">

      :   If <a>playback direction</a> is <code>normal</code>,
      ::  Let the <var>current direction</var> be forwards.

      :   If <a>playback direction</a> is <code>reverse</code>,
      ::  Let the <var>current direction</var> be reverse.

      : Otherwise,
      ::

          1.  Let <var>d</var> be the <a>current iteration</a>.

          2.  If <a>playback direction</a> is
              <code>alternate-reverse</code> increment
              <var>d</var> by 1.

          3.  Issue: 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 <a>iteration time</a> and
              <a>current iteration</a>.
              Is anything actually needed here?

          4.  If <code><var>d</var> % 2 == 0</code>, let the
              <var>current direction</var> be forwards, otherwise let
              the <var>current direction</var> be reverse.
              If <var>d</var> is infinity, let the <var>current direction</var>
              be forwards.

    </div>

3.  If the <var>current direction</var> is forwards then return
    the <a>iteration time</a>.

    Otherwise, return the <a>iteration duration</a>
    - <a>iteration time</a>.

<h3 id="time-transformations">Time transformations</h3>

<h4 id="scaling-the-time">Scaling the time</h4>

<div class="informative-bg"><em>This section is non-normative</em>

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

For such situations Web Animations provides <a>timing functions</a>
that scale the progress of an <a>animation node</a>.

<a>Timing functions</a> take an input time fraction and produce
a scaled output time fraction.

<div class="figure">
  <img src="img/timing-function-example.svg" width="350"
    alt="Example of a timing function that produces an ease-in effect.">
</div>
<p class="caption">
  Example of a timing function that produces an ease-in effect.
  Given an input timing fraction of 0.7, the timing function scales the
  value to produce an output time fraction of 0.52.<br>
  By applying this timing function, time will appear to progress more
  slowly at first but then gradually progress more quickly.
</p>

<a>Timing functions</a> are applied to an iteration of an <a>animation
node</a>.

</div>

<h4 id="timing-functions">Timing functions</h4>

A <dfn>timing function</dfn> 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).

<a>Animation nodes</a> have one <a>timing function</a> associated with
them.
The default <a>timing function</a> is the <dfn>linear timing
function</dfn> whose output is identical to its input.
The <a>linear timing function</a> can be represented by the string
&ldquo;linear&rdquo;.

The range of timing functions that may be applied to a given
<a>animation node</a> depends on the type of the <a>animation node</a>.

<div class="issue">
Currently, the set of <a>timing functions</a> allowed on
an <a>animation group</a> is not restricted.
This has raised concern about complexity of implementation and also
complexity of behavior with regards to fill modes.
As a result, allowing the full set of timing functions on animation
groups is considered <strong>at risk</strong>.

Alternatives are to either restrict timing functions on animation
groups to the <a>linear timing function</a> or to a set of
&ldquo;simple&rdquo; timing functions that have properties that
alleviate some of the concerns with the more complex timing
functions.

See <a
href="http://lists.w3.org/Archives/Public/public-fx/2013JulSep/0076.html">section
2 of the discussion from August 2013</a>.
</div>

<h4 id="scaling-using-a-cubic-bezier-curve">Scaling using a cubic B&eacute;zier curve</h4>

<div class="informative-bg"><em>This section is non-normative</em>

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

<div class="figure">
  <img src="img/cubic-bezier-timing-curve.svg" width="500"
      alt="A cubic Bezier curve used as a timing function.">
</div>
<p class="caption">
  A cubic B&eacute;zier curve used as a timing function.<br>
  The shape of the curve is determined by the location of the control
  points <var>P1</var> and <var>P2</var>.<br>
  Input time fractions serve as <var>x</var> values of the curve,
  whilst the <var>y</var> values are the output time fractions.
</p>

Some example cubic B&eacute;zier timing functions are illustrated below.

<div class="figure">
  <img src="img/curve-keywords.svg" width="500"
      alt="The timing functions produced by keyword values.">
</div>
<p class="caption">
  The timing functions produced by each of the keyword values
  associated with cubic B&eacute;ier timing functions accepted by the
  {{AnimationTiming/easing}} member of the {{AnimationTiming}} interface
  member from the <a href="#programming-interface">programming
  interface</a>.
</p>
</div>

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

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

A <a>cubic B&eacute;zier timing function</a> may be specified as a string
using the following syntax (using notation from [[!CSS3VAL]]):
<blockquote>
  <div
    class="production"><dfn>&lt;cubic-bezier-timing-function&gt;</dfn> =
    ease | ease-in | ease-out | ease-in-out |
    <span class="atom">cubic-bezier(&lt;number&gt;, &lt;number&gt;,
      &lt;number&gt;, &lt;number&gt;)</span></div>
</blockquote>

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(&lt;number&gt;, &lt;number&gt;, &lt;number&gt;, &lt;number&gt;)
::  Specifies a <a>cubic B&eacute;zier timing function</a>.
    The four numbers specify points <var>P1</var> and <var>P2</var> of
    the curve as (x1, y1, x2, y2).
    Both x values must be in the range [0, 1] or the definition is
    invalid.

<div class="issue">
It has been proposed to extend <code>cubic-bezier</code> to allow
multiple segments, using syntax such as the following:

<pre>
<code>cubic-bezier( [ &lt;number&gt;{6} ; ]* &lt;number&gt;{4} )</code>
</pre>

(i.e. the curve starts at (0, 0); each segment is defined by six
numbers where the start point is the end of the previous segment and
the numbers define the two control points and the end point. The
last segment is defined by four numbers since the end point is fixed
at (1, 1).)

This would provide a simple and compact syntax for tools trying to
map arbitrary curves (e.g. bounce functions) to timing functions.
</div>

<h4 id="timing-in-discrete-steps">Timing in discrete steps</h4>

<div class="informative-bg"><em>This section is non-normative</em>
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.

<div class="figure">
  <img src="img/step-timing-func-examples.svg" width="700"
      alt="Example step timing functions.">
</div>
<p class="caption">
  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.<br>
  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.
</p>

</div>

A <dfn>step timing function</dfn> is a type of <a>timing function</a>
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 <a href="#interval-timing"
section></a>), the output time at the transition point is
the time <em>after</em> applying the increase (i.e. the top of the
step) with the following exception.

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


1.  If the <a>active time</a> of the animation node is
    <a>unresolved</a>, the <a>before flag</a> is not set and these
    steps should be aborted.
2.  Determine the <var>current direction</var> using the procedure
    defined in <a href="#calculating-the-directed-time"
    section></a>.
3.  If either the <var>current direction</var> is <span
    class="prop-value">forwards</span> or the <a>animation node
    playback rate</a> &ge; 0 (but <em>not</em> when both conditions
    are true),
    let <var>going forwards</var> be true, otherwise it is false.
4.  The <a>before flag</a> is set if the animation node is in the
    <a>before phase</a> and <var>going forwards</var> is true;
    or if the animation node is in the <a>after phase</a> and
    <var>going forwards</var> is false.

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

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

<blockquote>
  <div class="production"><dfn>&lt;step-timing-function&gt;</dfn> =
    step-start | step-middle | step-end |
    <span class="atom">steps(&lt;integer&gt;[,
                       [ start | middle | end ] ]?)</span></div>
</blockquote>

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(&lt;integer&gt;[, [ start | middle | end ] ]?)
::  Specifies a <a>step timing function</a>.
    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 <span
    class="prop-value">end</span>.

<h4 id="calculating-the-transformed-time">Calculating the transformed time</h4>

The <dfn>transformed time</dfn> is calculated from the
<a>directed time</a> using the following steps:

1.  If the <a>directed time</a> is <a>unresolved</a>,
    return an <a>unresolved</a> <a>time value</a>.
2.  If the <a>iteration duration</a> is infinity,
    return the <a>directed time</a>.
3.  Let <var>iteration fraction</var> be the result of
    evaluating <code><a>directed time</a> / <a>iteration
    duration</a></code> unless <a>iteration duration</a> is
    zero, in which case let <var>iteration fraction</var> be
    zero.
4.  Let <var>scaled fraction</var> be the result of
    evaluating the <a>animation node</a>'s <a>timing function</a>
    with <var>iteration fraction</var> as the input time
    fraction.
5.  Return the result of evaluating <code><var>scaled
    fraction</var> &times; <a>iteration duration</a></code>.
    If the <var>scaled fraction</var> is zero, let the result be
    zero.

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


<h3 id="grouping-and-synchronization">Grouping and synchronization</h3>

<div class="informative-bg"><em>This section is non-normative</em>

While it is possible to set the timing properties of <a>animation
nodes</a> individually, it is often useful to synchronize <a>animation
nodes</a> so that they share common timing properties and maintain
their temporal relationship.  This is achieved using an <a>animation
group</a>.

A simple example is illustrated below.

<div class="figure">
  <img src="img/grouping-delay.svg" width="800"
        alt="Using groups to share common timing properties.">
</div>
<p class="caption">
  Using groups to share common timing properties.<br>
  (a) Shows setting a delay of 5 seconds on individual animations.<br>
  (b) Produces the same effect by setting the delay on the group.
</p>

When an <a>animation group</a> is <a>directly associated with
a player</a>, the <a>animation nodes</a> associated with the
<a>animation group</a> can be seeked, paused, and stopped as a unit.
</p>

</div>

An <dfn>animation group</dfn> is a type of <a>animation node</a> that
contains an ordered sequence of zero or more <a>animation nodes</a>
known as <dfn title="child animation node">child animation nodes</dfn>.

At a given moment, an <a>animation node</a> may be a <a>child animation
node</a> of at most one <a>animation group</a> known as the <dfn>parent
animation group</dfn>.
The <a>parent animation group</a> cannot be the same <a>animation
node</a> as the <a>child animation node</a> itself.

By nesting <a>animation groups</a> it is possible to create hierarchical
tree structures.
The following terms are used to describe the parts and properties of
such structures and are defined in [[!DOM]]:

*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-order">
    tree order</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-root">
    root</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-ancestor">
    ancestor</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-descendant">
    descendant</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-inclusive-ancestor">
    inclusive ancestor</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-inclusive-descendant">
    inclusive descendant</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-next-sibling">
    next sibling</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-previous-sibling">
    previous sibling</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-first-child">
    first child</a></dfn>
*   <dfn><a href="http://www.w3.org/TR/dom/#concept-tree-last-child">
    last child</a></dfn>

Note: in applying these definitions to <a>animation nodes</a>, the
    term <em>parent</em> refers exclusively to a <a>parent animation
    group</a> and does <em>not</em> include the <a>player</a> which with
    an <a>animation node</a> may be <a
    title="directly associated with a player">directly associated</a>
    despite the fact that conceptually the <a>player</a> acts as a parent
    time source.

The temporal relationship between a <a>child animation node</a> and its
<a>parent animation group</a> is incorporated in the definition of
<a>inherited time</a> (see <a href="#local-time-and-inherited-time"
section></a>).

<h4 id="relationship-of-group-time-to-child-time">Relationship of group time to child time</h4>

<div class="informative-bg"><em>This section is non-normative</em>

The timing of the children of an <a>animation group</a> is based on
the timing of the group.
Specifically, times for the children are based on the parent's
<a>transformed time</a>.
With regards to repetition, this means the children operate
<em>inside</em> an iteration of the parent.

For example, if an <a>animation group</a> has an <a>iteration
count</a> of 2, then the children of of the group will all play twice
since they effectively play <em>inside</em> the group's iterations.

<div class="figure">
  <img src="img/grouping-repetition.svg" width="600"
    alt="The effect of multiple iterations on the children of a group.">
</div>
<p class="caption">
  Since children of an <a>animation group</a> base their timing on the
  group's <a>transformed time</a>, when the group repeats, the
  children play again.
</p>

Note that even in this case, the child <a>animation nodes</a> still
have only <em>one</em> <a>active interval</a>.
However, as a result of the parent's timing, the <a>active
interval</a> is played twice.

If an <a>iteration count</a> is specified for the children of a group
as well as for the group itself, the effect is as if the <a>iteration
count</a> of the group was multiplied with the <a>iteration count</a>
of the children.

<div class="figure">
  <img src="img/grouping-repetition-and-animation-repetition.svg"
    width="600" alt="Iteration counts are multiplicative.">
</div>
<p class="caption">
  Specifying an <a>iteration count</a> of 2 on an <a>animation group</a>
  and an <a>iteration count</a> of 3 on one of its children results in
  that child playing 6 times.
</p>

A further result of the children of an <a>animation group</a> basing
their timing on the group's <a>transformed time</a> is that they
cannot animate outside of the group's <a>active interval</a>.
This is because the <a>transformed time</a> of a group will not
change outside its <a>active interval</a>.
This allows groups to <em>clip</em> the playback of their children.

<div class="figure">
  <img src="img/grouping-clipping.svg" width="600"
    alt="Groups clip the active interval of contained children.">
</div>
<p class="caption">
  In the first instance, an <a>animation node</a> has a negative delay
  and an infinite <a>iteration count</a>.<br>
  However, when a similar <a>animation node</a> is placed inside
  an <a>animation group</a> with a specified <a>iteration duration</a>
  it has the effect of clipping the child <a>animation node</a>'s
  <a>active interval</a>.
</p>

Some further consequences of <a>animation group</a> children basing
their timing on their parent group's <a>transformed time</a> are:

*   Setting the <a title="animation node playback rate">playback
    rate</a> of an <a>animation group</a> will speed up or slow down all
    children.

*   Changing the <a>playback direction</a> of an <a>animation group</a>
    will change the direction of all children.

*   Applying a <a>timing function</a> to an <a>animation group</a> will
    affect the progress of all children.

</div>

<h4 id="the-start-time-of-children-of-an-animation-group">The start time of children of an animation group</h4>

The <a title="animation node start time">start time</a> of a <a>child
animation node</a> of an <a>animation group</a> is zero.

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

<h4 id="the-intrinsic-iteration-duration-of-an-animation-group">The intrinsic iteration duration of an animation group</h4>

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

1.  Define the <a>end time</a> of an <a>animation node</a> as:

    <blockquote>
      <dfn>end time</dfn> =
      <code><a title="animation node start time">start time</a> +
      <a>start delay</a> + <a>active duration</a> + <a>end
      delay</a></code>
    </blockquote>

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

    <div class="switch">

    :   If the group has no <a>child animation nodes</a>,
    ::  the <a>intrinsic iteration duration</a> is zero.

    :   Otherwise,
    ::

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

    </div>

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

<h4 id="animation-sequences">Animation sequences</h4>

<div class="informative-bg"><em>This section is non-normative</em>

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

Compare the two arrangements illustrated below:

<div class="figure">
  <img src="img/grouping-types.svg" width="600"
    alt="Animation groups and animation sequences.">
</div>
<p class="caption">
  Animation groups and animation sequences.<br>
  (a) is a regular <a>animation group</a> where all the children run
      simultaneously.<br>
  (b) is an <a>animation sequence</a> where the children run in turn.
</p>

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

<div class="figure">
  <img src="img/grouping-nesting.svg" width="600"
    alt="Nesting of animation groups.">
</div>
<p class="caption">
  An <a>animation sequence</a> that contains a regular <a>animation
  group</a> as a child.<br>
  The <a>animation group</a> waits for the previous child of the
  <a>animation sequence</a> to finish, and then the children of the
  <a>animation group</a> play simultaneously.
  After they have finished the next child of the <a>animation
  sequence</a> plays.
</p>

</div>

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

<h5 id="the-start-time-of-children-of-an-animation-sequence">The start time of children of an animation sequence</h5>

The <a title="animation node start time">start time</a> of
a <a>child animation node</a> of an <a>animation sequence</a> is the
<a>end time</a> of the child's <a>previous sibling</a>.
If the child has no <a>previous sibling</a> the start time is zero.

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

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

<div class="informative-bg"><em>This section is non-normative</em>

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

<div class="figure">
  <img src="img/sequence-groups-and-start-delays.svg" width="600"
    alt="Using negative start delays to overlap children of seq
        groups">
</div>
<p class="caption">
  Example of using the <a>start delay</a> on children of an
  <a>animation sequence</a> to shift their timing so that they
  overlap (a negative delay) or are spaced apart (a positive delay).
</p>

A negative <a>start delay</a> can be used to cause the <a>active
interval</a> of two children to overlap.
Note that the <a>start delay</a> affects the <a
title="animation node start time">start time</a> of subsequent
children in the group.

</div>

<h5 id="the-intrinsic-iteration-duration-of-an-animation-sequence">The intrinsic iteration duration of an animation sequence</h5>

The <a>intrinsic iteration duration</a> of an <a>animation
sequence</a> is equivalent to the <a
title="animation node start time">start time</a> of a hypothetical
<a>child animation node</a> appended to the group's children
calculated according to the definition in <a
href="#the-start-time-of-children-of-an-animation-sequence"
section></a> unless that produces a negative value, in
which case the <a>intrinsic iteration duration</a> is zero.

As a result, if the <a>animation sequence</a> has no <a>child
animation nodes</a> the <a>intrinsic iteration duration</a> will be
zero.

<h3 id="animations">Animations</h3>

<dfn id="concept-animation">Animations</dfn> are a kind of <a>animation
node</a> that apply an <a>animation effect</a> or a <a>custom effect</a>
to an element or pseudo-element such as <code>::before</code> or
<code>::after</code> [[!SELECT]] referred to as the <dfn>animation
target</dfn>.

<h4 id="calculating-the-time-fraction">Calculating the time fraction</h4>

Before passing the <a>transformed time</a> of an <a>animation</a> to
its <a>animation effect</a> it is converted to a <em>time
fraction</em>.
The <dfn>time fraction</dfn> of an <a>animation node</a> is calculated
by running the steps corresponding to the first matching condition from
the following:

<div class="switch">

:   If the <a>transformed time</a> is <a>unresolved</a>, return
    an <a>unresolved</a> <a>time value</a>.
:   If the <a>iteration duration</a> is zero,
::  the <a>time fraction</a> is as follows,

    <div class="switch">

    :   If <a>local time</a> &lt; <a>start delay</a>,
    ::  Return the result of recalculating the <a>transformed time</a>
        using an <a>iteration duration</a> of 1.

    :   Otherwise,
    ::

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

    </div>

:   Otherwise,
::  Return <a>transformed time</a> / <a>iteration duration</a>.

</div>

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

<!-- End of timing model -->



<h2 id="animation-model">Animation Model</h2>

<div class='informative-bg'><em>This section is non-normative</em>

The Web Animations <em>animation model</em> takes the <a>time
fractions</a> and <a>current iteration</a> values produced by the
<em>timing model</em> for a given <a>animation</a> and
applies it as the input to the <a>animation</a>'s
<a>animation effect</a>.

The output of each <a>animation effect</a> is then combined with other
<a>animation effects</a> using an <a>animation stack</a> before being
applied to the target properties (see <a href="#combining-animations"
section></a>).

</div>

<h3 id="animation-effects">Animation effects</h3>

An <dfn>animation effect</dfn> takes a <a>time fraction</a> and
a <a>current iteration</a> value and uses them to calculate an
<a>intermediate animation value</a> for its <a
title="target property">target properties</a>.  Each <a>animation</a>
may have at most one <a>animation effect</a> associated with it.

Since the result of an <a>animation effect</a> is based on the
<a>time fraction</a> and <a>current iteration</a> value, it is updated
whenever the timing model is <a title="sampling">sampled</a>.

<h4 id="target-properties">Target properties</h4>

Each <a>animation effect</a> can have zero or more associated
<dfn title="target property">target properties</dfn>.

<a title="target property">Target properties</a> may be CSS properties
or DOM attributes.
If a given <a>animation target</a> has an attribute with the same name
as a CSS property, any <a>target property</a> of that name is taken to
refer to to the CSS property.

Note: If there ever exists a situation where we need to animate an attribute
      with the same name as a property (other than a <a
      href="http://www.w3.org/TR/SVG2/intro.html#TermPresentationAttribute">presentation
      attribute</a> [[SVG2]]) then we will need to introduce
      a disambiguation strategy. Generally, however, such naming should be
      avoided.

<h4 id="procedures-for-animating-properties">Procedures for animating properties</h4>

Unless specifically defined not to be, all properties are considered
<dfn id="concept-animatable">animatable</dfn>.
In order to animate a <a>target property</a>, the following procedures
must be defined.

*   <dfn title="animation interpolation">interpolation</dfn> &mdash;
    given two target property values <var>V</var><sub>start</sub> and
    <var>V</var><sub>end</sub>, produces an intermediate value
    <var>V</var><sub>res</sub> at a distance of <var>p</var> along the
    interval between <var>V</var><sub>start</sub> and
    <var>V</var><sub>end</sub> such that
    <var>p</var> = 0 produces <var>V</var><sub>start</sub> and
    <var>p</var> = 1 produces <var>V</var><sub>end</sub>.
    The range of <var>p</var> is (&minus;&infin;, &infin;) due to the
    effect of <a>timing functions</a>.
    As a result, this procedure must also define extrapolation
    behavior for <var>p</var> outside [0, 1].

*   <dfn title="animation addition">addition</dfn> &mdash; given two
    target property values
    <var>V</var><sub>a</sub> and <var>V</var><sub>b</sub>, returns the
    sum of the two properties, <var>V</var><sub>result</sub>.
    For addition that is not commutative (for example, matrix
    multiplication) <var>V</var><sub>a</sub> represents the first term
    of the operation and <var>V</var><sub>b</sub> represents the
    second.

    <div class='informative-bg'><em>This section is non-normative</em>

    While <a title="animation addition">addition</a> can often be
    expressed in terms of the same weighted sum function used to
    define <a title="animation interpolation">interpolation</a>,
    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.

    </div>

*   <dfn title="animation accumulation">accumulation</dfn> &mdash;
    given two target property values
    <var>V</var><sub>a</sub> and <var>V</var><sub>b</sub>, returns the
    result, <var>V</var><sub>result</sub>, of combining
    the two operands such that <var>V</var><sub>b</sub> is treated as
    a <em>delta</em> from <var>V</var><sub>a</sub>.
    For accumulation that is not commutative (for example,
    accumulation of mismatched transform lists)
    <var>V</var><sub>a</sub> represents the first term of the
    operation and <var>V</var><sub>b</sub> represents the second.

    <div class='informative-bg'><em>This section is non-normative</em>

    For many types of animation such as numbers or lengths, <a
    title="animation accumulation">accumulation</a> is defined to
    be identical to <a title="animation addition">addition</a>.

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

    </div>

*   <dfn>distance computation</dfn> &mdash; given two target property
    values <var>V</var><sub>start</sub> and
    <var>V</var><sub>end</sub>, calculates some notion of scalar
    distance between the values, <var>distance</var>.

<h4 id="specific-animation-behaviors">Specific animation behaviors</h4>

The specific procedures used for animating a given <a>target
property</a> are referred to as the property's <dfn>animation
behavior</dfn>.

The <a>animation behavior</a> 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.

Issue: The default <a>animation behavior</a> for CSS properties is "as
       string".  Should this be defined here or in CSS Animations Level 4?

For DOM attributes, the <a>animation behavior</a> is defined alongside
the attribute definition.
Unlike CSS properties, if such a definition is not provided the
default <a>animation behavior</a> is &ldquo;<a>not animatable</a>&rdquo;.

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

For <a>animation behaviors</a> that do not define a specific procedure
for <a title="animation addition">addition</a> or which are defined as
<dfn>not additive</dfn>, the <a
title="animation addition">addition procedure</a> is simply
<var>V</var><sub>res</sub> = <var>V</var><sub>b</sub>.

For <a>animation behaviors</a> that do not define a specific procedure
for <a title="animation accumulation">accumulation</a>, the <a
title="animation accumulation">accumulation procedure</a> is identical
to the <a title="animation addition">addition procedure</a> for that
behavior.

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

<h5 id="not-animatable-section">Not animatable</h5>

Some properties are specifically defined as <dfn
id="concept-not-animatable">not animatable</dfn>.
For example, properties defining animation parameters are <a>not animatable</a>
since doing so would create complex recursive behavior.

Unlike other <a>animation behaviors</a>, no procedures for
<a title="animation interpolation">interpolation</a>,
<a title="animation addition">addition</a> and <a>distance
computation</a> are defined for properties whose <a>animation
behavior</a> is <a>not animatable</a> since these
properties should not be modified.

An <a>animation effect</a> that targets a property that is
<a>not animatable</a> will still exhibit the
usual behavior for an <a>animation node</a> such as occupying time in an
<a>animation sequence</a> and delaying the fulfilment of a <a>player</a>'s
<a>current finished promise</a>.

<h5 id="animatable-as-string-section">Animatable as string</h5>

A <a>target property</a> that is <dfn>animatable as string</dfn>
has the following <a>animation behavior</a>:

*   <a title="animation interpolation">interpolation</a>:
    <div role="math" aria-describedby="math-string-interpolation"
    style="display: inline">
    <math xmlns="http://www.w3.org/1998/Math/MathML">
      <msub><mi>V</mi><mn>res</mn></msub><mo>=</mo>
      <mrow>
        <mfenced open="{" close="">
          <mtable>
            <mtr>
              <mtd columnalign="left">
                <msub><mi>V</mi><mn>start</mn></msub>
              </mtd>
              <mtd columnalign="left">
                <mtext>if&nbsp;</mtext><mi>p</mi>
                <mo>&lt;</mo><mn>0.5</mn>
              </mtd>
            </mtr>
            <mtr>
              <mtd columnalign="left">
                <msub><mi>V</mi><mn>end</mn></msub>
              </mtd>
              <mtd columnalign="left">
                <mtext>if&nbsp;</mtext><mi>p</mi>
                <mo>&ge;</mo><mn>0.5</mn>
              </mtd>
            </mtr>
          </mtable>
        </mfenced>
      </mrow>
    </math>
    <div id="math-string-interpolation">
      <var>V</var><sub>res</sub> =
        <var>V</var><sub>start</sub>, if <var>p</var> &lt; 0.5 or
        <var>V</var><sub>end</sub>, if <var>p</var> &ge; 0.5
    </div>
    </div>

<h5 id="animatable-as-real-number-section">Animatable as real number</h5>

A <a>target property</a> that is <dfn>animatable as real
number</dfn> has the following <a>animation behavior</a>:

*   <a title="animation interpolation">interpolation</a>:
    <var>V</var><sub>res</sub> =
      (1 - <var>p</var>) &times; <var>V</var><sub>start</sub> +
      <var>p</var> &times; <var>V</var><sub>end</sub>
*   <a title="animation addition">addition</a>:
      <var>V</var><sub>a</sub> + <var>V</var><sub>b</sub>
*   <a>distance computation</a>:
    <var>distance</var> =
      |<var>V</var><sub>end</sub> - <var>V</var><sub>start</sub>|

<h5 id="animatable-as-length-percentage-or-calc-section">Animatable as length, percentage, or calc</h5>

A <a>target property</a> that is <dfn>animatable as length,
percentage, or calc</dfn> has the following <a>animation
behavior</a>:

*   <a title="animation interpolation">interpolation</a>:
    as defined in [[CSS3-TRANSITIONS]].
*   <a title="animation addition">addition</a>:
    calc(<var>V</var><sub>a</sub> + <var>V</var><sub>b</sub>)<br>
    (Nested <code>calc()</code> functions are expanded when
    determining the computed value as defined in <a
    href="http://www.w3.org/TR/css3-values/#calc-computed-value">CSS
    Values and Units</a> [[!CSS3VAL]].)
*   <a>distance computation</a>: as with <a>animatable as real
    number</a> but using the <a
    href="http://www.w3.org/TR/CSS2/cascade.html#used-value">used
    value</a> [[!CSS21]] for <var>V</var><sub>start</sub> and
    <var>V</var><sub>end</sub>.

<h5 id="animatable-as-color-section">Animatable as color</h5>

A <a>target property</a> that is <dfn>animatable as color</dfn> has
the following <a>animation behavior</a>:

*   <a title="animation interpolation">interpolation</a>:
    as defined in [[CSS3-TRANSITIONS]].
*   <a title="animation addition">addition</a>:
    as with <a>animatable as real number</a> but performed on each
    RGBA color component in premultiplied space.

    Note: Since negative color is not currently supported, clamping of
          the channel values may be performed upon each addition or once
          when <a>composition</a> is complete.
    </p>
*   <a>distance computation</a>:
    <div role="math" aria-describedby="math-color-distance">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
      <mrow>
        <mi>distance</mi><mo>=</mo>
        <msqrt>
          <msup>
            <mrow>
              <mfenced open="(" close=")" separators=",">
                <mrow><msub><mi>R</mi><mn>end</mn></msub>
                      <mo>-</mo>
                      <msub><mi>R</mi><mn>start</mn></msub></mrow>
              </mfenced>
            </mrow><mn>2</mn>
          </msup>
          <mo>+</mo>
          <msup>
            <mrow>
              <mfenced open="(" close=")" separators=",">
                <mrow><msub><mi>G</mi><mn>end</mn></msub>
                      <mo>-</mo>
                      <msub><mi>G</mi><mn>start</mn></msub></mrow>
              </mfenced>
            </mrow><mn>2</mn>
          </msup>
          <mo>+</mo>
          <msup>
            <mrow>
              <mfenced open="(" close=")" separators=",">
                <mrow><msub><mi>B</mi><mn>end</mn></msub>
                      <mo>-</mo>
                      <msub><mi>B</mi><mn>start</mn></msub></mrow>
                </mfenced>
            </mrow><mn>2</mn>
          </msup>
          <mo>+</mo>
          <msup>
            <mrow>
              <mfenced open="(" close=")" separators=",">
                <mrow><msub><mi>A</mi><mn>end</mn></msub>
                      <mo>-</mo>
                      <msub><mi>A</mi><mn>start</mn></msub></mrow>
              </mfenced>
            </mrow><mn>2</mn>
          </msup>
        </msqrt>
      </mrow>
      </math>

      <div id="math-color-distance">
      distance = sqrt((R<sub>end</sub> - R<sub>start</sub>)^2 + (G<sub>end</sub> - G<sub>start</sub>)^2 + (B<sub>end</sub> - B<sub>start</sub>)^2 + (A<sub>end</sub> - A<sub>start</sub>)^2)
      </div>

    </div>

    where &lt;<var>R|G|B|A</var><sub>start|end</sub>&gt;
    represents the red, green, blue, or alpha channel of
    <var>V</var><sub>start</sub> or <var>V</var><sub>end</sub>
    respectively.
    Each value is normalized to the [0.0, 1.0] range and expressed
    in premultiplied color space.

<h5 id="animatable-as-transform-list-section">Animatable as transform list</h5>

A <a>target property</a> that is <dfn>animatable as transform
list</dfn> has the following <a>animation behavior</a>:

*   <a title="animation interpolation">interpolation</a>:
    as defined in <a
    href="http://www.w3.org/TR/css3-transforms/#interpolation-of-transforms">Interpolation
    of Transforms</a> [[CSS3-TRANSFORMS]].

*   <a title="animation addition">addition</a>: performed by
    concatenating transform lists as
    &lsquo;<var>V</var><sub>a</sub> <var>V</var><sub>b</sub>&rsquo;.

*   <a title="animation accumulation">accumulation</a>:

    1.  Beginning at the end of each list, <var>V</var><sub>a</sub>
        and <var>V</var><sub>b</sub>,
        find the largest contiguous portion of each list where the
        corresponding list elements from each list have the same
        transform type.
        Call the matching portions from <var>V</var><sub>a</sub> and
        <var>V</var><sub>b</sub>, <var>V</var><sub>matching-a</sub>
        and
        <var>V</var><sub>matching-b</sub> respectively and likewise
        <var>V</var><sub>remainder-a</sub> and
        <var>V</var><sub>remainder-b</sub> for the non-matching
        parts.
        <p class="issue">
          We should probably expand 2d functions to their 3d
          equivalents before matching?
        </p>
    2.  Let <var>V</var><sub>combined</sub> be a transform list
        combining <var>V</var><sub>matching-a</sub> and
        <var>V</var><sub>matching-b</sub> by adding the numeric
        components of each corresponding function.
        <p class="issue">
          This needs to be more specific, e.g. when combining
          <code>translate(20px)</code> and <code>translate(30px
          10px)</code> we have to expand the first function to
          <code>translate(20px 0px)</code> first.
          Probably need to define unit conversion too.
        </p>
    3.  The result of accumulation is a transform list created by <a
        title="animation addition">adding</a> the combined result
        with the non-matching portions of the two lists as follows:
        &lsquo;<var>V</var><sub>remainder-a</sub>
        <var>V</var><sub>remainder-b</sub>
        <var>V</var><sub>combined</sub>&rsquo;.

*   <a>distance computation</a>: <span class="todo">See issue
    below</span>

<div class="issue">

    For <a>distance computation</a> we previously defined it as follows:

    1.  Look only at the first component of the two lists
    2.  If both are translate &rarr; euclidean distance
    3.  If both are scale &rarr; absolute difference
    4.  If both are rotate &rarr; absolute difference
    5.  If both match but are something else &rarr; use linear
    6.  If they don't match &rarr; use matrix decomposition and
        euclidean distance between translate components

    This seems really arbitrary, especially part 5.

    Also, looking at only the first component seems odd.
    Going through each component, working out the distance and then
    getting the square of the distance also seems much more consistent
    with what we do elsewhere.

</div>

<h5 id="other-animation-behaviors">Other animation behaviors</h5>

The set of <a>animation behaviors</a> defined here may be extended
by other specifications.
For example, properties with using the &lt;image&gt; type are
animated using the interpolation behavior defined in <a
href="http://dev.w3.org/csswg/css-images-4/#interpolation">CSS Image
Values and Replaced Content</a>
[[CSS4-IMAGES]].

<div class="issue">

    There are a bunch of CSS properties for which distance (and in
    some cases addition) is not defined or which need special
    handling.

    For example,

    *   font-stretch (an enum but handled like an integer)
    *   visibility (0 or 1 depending on if endpoints match or not)
    *   flex-grow and flex-shrink which allow animation only if one of
        the endpoints is 0)
    *   value pairs, triples (use square distance)
    *   rects (use square distance)
    *   dash arrays (square distance but a bit weird due to
        percentages)
    *   shadows (square distance of components)
    *   filters (undefined)
    *   background-position (special list handling needed)
    *   pair lists

    Should we define these here or in the CSS Animation 4 spec?

</div>

<h4 id="intermediate-animation-values">Intermediate animation values</h4>

Given a <a>time fraction</a>, a <a>current iteration</a>, and an
<a>underlying value</a>, an <a>animation effect</a> produces
an <dfn>intermediate animation value</dfn> for each <a>animatable</a>
<a>target property</a>.
The procedure for calculating this value depends on the specific
type of <a>animation effect</a> and is defined subsequently (see <a
href="#the-intermediate-animation-value-of-a-keyframe-animation-effect"
section></a>).

Before being applied to the <a title="target property">target
properties</a>,
these <a>intermediate animation values</a> are composed together using
the process defined in <a href="#combining-animations" section></a>.

<h3 id="combining-animations">Combining animations</h3>
<div class='informative-bg'><em>This section is non-normative</em>

After calculating the <a>intermediate animation values</a> for an
<a>animation effect</a>, they are applied to the <a>animation
effect</a>'s <a title="target property">target properties</a>.

Since it is possible for multiple <a>in effect</a> <a>animations</a> to target
the same property it is often necessary to combine the results of several
<a>animation effects</a> together.
This process is called <dfn title='composition'>compositing</dfn> and is
based on establishing an <a>animation stack</a> for each property
targetted by an <a>in effect</a> <a>animation effect</a>.

After compositing the results of <a>animation
effects</a> together, the composited result is combined with other
values specified for the <a>target property</a>.

For a CSS <a>target property</a> the arrangement is illustrated below:

<div class="figure">
<img src="img/animation-cascade.svg" width="450"
alt="Overview of the application of intermediate animation values
to their target properties">
</div>
<p class="caption">
Overview of the application of <a>intermediate animation values</a> to
their <a>target properties</a>.<br>
The results of <a>animation effects</a> targetting the same property
are composited together using an <a>animation stack</a>.<br>
The result of this composition is written to an animation stylesheet
that is more important than other stylesheets but less than any
<code>!important</code> rules.
</p>

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

For the first part of this operation&mdash;combining <a>intermediate
animation values</a> that target the same <a
title="target property">property</a>&mdash; it is necessary to
determine both
<em>how</em> the <a>animation effects</a>
associated with the <a>animations</a> are combined
with one another,
as well as the <em>order</em> in which they are applied, that is,
their relative <em>priority</em>.

The matter of <em>how</em> <a>intermediate animation values</a> are
combined is governed by the <a>composite operation</a> of
the corresponding <a>animation effects</a>.

The relative <em>priority</em> of <a>intermediate animation values</a>
is determined by an <a>animation stack</a> established for each
animated property.
</div>

<h4 id="the-animation-stack">The animation stack</h4>

Associated with each property <a title="target property">targetted</a>
by one or more <a>animation effects</a> is an <dfn>animation
stack</dfn> that establishes the relative priority of the <a>animation
effects</a>.

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

1.  Let the <dfn>associated player of an animation effect</dfn>
    be the <a>player</a> <a
    title="associated with a player">associated</a> with the
    <a>animation</a> that is applying the <a>animation
    effect</a> to the property with which this <a>animation stack</a> is
    associated.
2.  Sort <var>A</var> and <var>B</var> by applying the following
    conditions in turn until the order is resolved,

    1.  Sort <var>A</var> and <var>B</var> using any <a>custom
        player priority</a> specified for the <a
        title="associated player of an animation effect">associated
        player</a> of each of <var>A</var> and
        <var>B</var> so that lower priorities sort first.
    2.  Sort by the <a>player sequence number</a> so that lower
        sequence numbers sort first.
    3.  Sort <var>A</var> and <var>B</var> in <a>tree order</a>.
        (By this point, <var>A</var> and <var>B</var> must have the
        same <a>player</a> since otherwise the order would have been
        resolved in the previous step.)

<a>Animation effects</a> that sort earlier have <em>lower</em>
priority.

<h5 id="the-custom-player-priority">The custom player priority</h5>

Each <a>player</a> has an associated numeric <dfn>custom player
priority</dfn> that is used to provide high-level control of
animation priority for specifications layered on top of Web
Animations.
The initial value of the <a>custom player priority</a> is zero.

<div class="note">

Note that the <a>custom player priority</a> is primarily
intended to be used to prioritize animations at
a high-level, such as to prioritize animations <em>by type</em>.
For example, it can be used to ensure that CSS Animations always
override CSS Transitions.

It is possible to control animation priority at a lower-level by
setting the <a>player start time</a> appropriately,
(possibly after making compensatory adjustments to the <a>start
delay</a> of the <a>source content</a>) or influencing the
<a>player sequence number</a> by controlling when <a>players</a>
are created.

</div>

<h4 id="calculating-the-result-of-an-animation-stack">Calculating the result of an animation stack</h4>

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

Each step in the process of evaluating an <a>animation stack</a> takes
an <dfn>underlying value</dfn> as input.

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

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

<h4 id="animation-composition">Animation composition</h4>

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

This specification defines three <a>composite operations</a> as
follows:

:   <dfn title="composite operation replace">replace</dfn>
::  The result of compositing the <a>intermediate animation value</a>
    with the <a>underlying value</a> is simply the <a>intermediate
    animation value</a>.
:   <dfn title="composite operation add">add</dfn>
::  The <a>intermediate animation value</a> is <a
    title="animation addition">added</a> to the <a>underlying
    value</a>.
    For <a>animation behaviors</a> where the
    <a title="animation addition">addition operation</a> is defined
    such that it is not commutative, the order of the operands is
    <code><a>underlying value</a> + <a>intermediate animation
    value</a></code>.
:   <dfn title="composite operation accumulate">accumulate</dfn></dt>
::  The <a>intermediate animation value</a> is <a
    title="animation accumulation">accumulated</a>
    onto the <a>underlying value</a>.
    For <a>animation behaviors</a> where the
    <a title="animation accumulation">accumulation operation</a> is
    defined such that it is not commutative, the order of the operands
    is <a>underlying value</a> followed by <a>intermediate animation
    value</a>.

<h4 id="applying-the-composited-result">Applying the composited result</h4>

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

<h5 id="applying-the-result-to-a-css-property">Applying the result to a CSS property</h5>

Applying a <a>composited value</a> to a CSS <a>target property</a>
depends on establishing an <a>animation stylesheet</a>.

The <dfn>animation stylesheet</dfn> contains
<a title="composited value">composited animation values</a>
and acts with a higher priority than all other stylesheets.
However, <code>!important</code> rules from all other stylesheets
act with a higher priority than the <a>animation stylesheet</a>.
The <a>animation stylesheet</a> is regenerated each time the
animation model is updated (see <a href="#animation-effects"
section></a>).

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

1.  Calculate the <var>base value</var> of the property as
    the value generated for that property by computing the <a
    href="http://www.w3.org/TR/CSS2/cascade.html#used-value">used
    value</a> [[!CSS21]] for that property in the absence of the
    <a>animation stylesheet</a>.
2.  Establish the <a>animation stack</a> for the property (see <a
    href="#the-animation-stack" section></a>).
3.  Calculate the <a>composited value</a> of the <a>animation
    stack</a> passing in the <var>base value</var> of the property
    as the initial <a>underlying value</a> (see <a
    href="#calculating-the-result-of-an-animation-stack"
    section></a>).
4.  Insert the <a>composited value</a> into the <a>animation
    stylesheet</a>.

<h5 id="applying-the-composited-result-to-a-dom-attribute">Applying the composited result to a DOM attribute</h5>

DOM attributes are, unless otherwise specified, <a>not animatable</a>.
For each attribute that has a specific <a>animation behavior</a>
associated with it, an attribute value to use when the attribute is
not specified or in error must be defined, referred to as the
<dfn>lacuna value</dfn>.
For example, SVG2 ([[SVG2]]) defines <a
href="http://www.w3.org/TR/SVG2/intro.html#TermLacunaValue">lacunae
values</a> for its attributes.

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

1.  Let the <var>base value</var> of the property be the value
    specified for attribute in the DOM or,
    if the attribute value is not specified in the DOM, the
    <a>lacuna value</a> for that attribute.
2.  Establish the <a>animation stack</a> for the property (see <a
    href="#the-animation-stack" section></a>).</li>
3.  Calculate the <a>composited value</a> of the <a>animation
    stack</a> passing in the <var>base value</var> of the attribute
    as the initial <a>underlying value</a> (see <a
    href="#calculating-the-result-of-an-animation-stack"
    section></a>).</li>
4.  Record the <a>composited value</a> as the <dfn>animated
    attribute value</dfn> of the attribute.

The <a>animated attribute value</a> does not replace the value of
the attribute in the DOM although it may be accessible via some
other interface.
For all intents and purposes other than interaction with DOM
interfaces, user agents must treat the <a>animated attribute
value</a> as the attribute value.

<h4 id="animation-accumulation-section">Animation accumulation</h4>

Similar to the compositing performed between <a>intermediate animation
values</a> (see <a href="#animation-composition"
section></a>), the <dfn>iteration composite operation</dfn>
determines how values are combined between successive iterations of
the same <a>animation</a>.

This specification defines two <a>iteration composite operations</a>
as follows:

:   <dfn title="iteration composite operation replace">replace</dfn>
::  Each successive iteration is calculated independently of previous
    iterations.
:   <dfn title="iteration composite operation accumulate">accumulate
::  Successive iterations of the animation are <a
    title="animation accumulation">accumulated</a> with the
    final value of the previous iteration.

    The application of the <a>iteration composite operation</a> is
    incorporated in the calculation of the <a>intermediate animation
    value</a> for each type of <a>animation effect</a>.

<h3 id="keyframe-animation-effects">Keyframe animation effects</h3>

A <dfn>keyframe animation effect</dfn> is an <a>animation effect</a>
that produces <a>intermediate animation values</a> for its <a>target
properties</a> by interpolating between a series of property values
positioned at fractional offsets.

Each set of property values indexed by an offset is called
a <dfn>keyframe</dfn>.

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

The behavior when <a>keyframes</a> overlap or have unsupported values
is defined in <a
href="#the-intermediate-animation-value-of-a-keyframe-animation-effect"
section></a>.

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

In addition to the <a>composite operation</a> specified on the
<a>animation effect</a>, each <a>keyframe</a> may also have an
associated <a>composite operation</a> that is applied to all values
specified in that <a>keyframe</a>.
If no <a>composite operation</a> is specified for a <a>keyframe</a>,
the <a>composite operation</a> specified for the <a>animation
effect</a> is used.

<h4 id="spacing-keyframes">Spacing keyframes</h4>
<div class="informative-bg"><em>This section is non-normative.</em>

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

For example, rather than typing:

<pre class='example sh_javascript'>
elem.animate([ { color: 'blue', offset: 0 },
               { color: 'green', offset: 1/3 },
               { color: 'red', offset: 2/3 },
               { color: 'yellow', offset: 1 } ], 2000);
</pre>

It should be possible to type the following and allow the user agent
to calculate the <a title="keyframe offset">offset</a> of each
keyframe:

<pre class='example sh_javascript'>
elem.animate([ { color: 'blue' },
               { color: 'green' },
               { color: 'red' },
               { color: 'yellow' } ], 2000);
</pre>

Web Animations provides spacing modes for this purpose. The default
spacing mode for keyframe animation effects is
&ldquo;<a
title="distribute keyframe spacing mode">distribute</a>&rdquo; which
produces the result described above.

The other spacing mode, &ldquo;<a
title="paced keyframe spacing mode">paced</a>&rdquo;, 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:

<pre class='example sh_javascript'>
elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px' },
               { left: '50px' } ], 1000);
</pre>

The resulting value of the <span class="prop-name">left</span>
property is illustrated below:

<div class="figure">
<img src="img/spacing-distribute.svg" width="350"
     alt="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.">
</div>
<p class="caption">
The animated value of the left property over time when applying the
<a title="distribute keyframe spacing mode">distribute</a> 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.
</p>

We can use the <a title="paced keyframe spacing mode">paced</a>
spacing mode as follows:

<pre class='example sh_javascript'>
elem.animate(
  new KeyframeEffect([ { left: '0px' },
                       { left: '-20px' },
                       { left: '100px' },
                       { left: '50px' } ], { spacing: "paced(left)" }), 1000);
</pre>

The result is illustrated below:

<div class="figure">
<img src="img/spacing-paced.svg" width="350"
     alt="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.">
</div>
<p class="caption">
The animated value of the left property over time when applying the
<a title="paced keyframe spacing mode">paced</a> spacing mode.
The absolute value of the slope is graph is equal for all segments
of the animation indicating a constant rate of change.
</p>

It is also possible to combine fixed <a>keyframe offsets</a> with
spacing modes as follows:

<pre class='example sh_javascript'>
elem.animate(
  new KeyframeEffect([ { left: '0px' },
                       { left: '-20px' },
                       { left: '100px', offset: 0.5 },
                       { left: '50px' } ], { spacing: "paced(left)" }), 1000);
</pre>

The result is illustrated below:

<div class="figure">
<img src="img/spacing-paced-with-offset.svg" width="350"
     alt="The animated value of the left property over time when applying the paced spacing mode and a fixed 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.">
</div>
<p class="caption">
The animated value of the left property over time when applying the
<a title="paced keyframe spacing mode">paced</a> spacing mode and
a fixed <a>keyframe offset</a> 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.
</p>
</div>

Before calculating animation values from a <a>keyframe animation
effect</a>, an absolute value must be computed for the <a>keyframe
offset</a> of each <a>keyframe</a> with a null offset.
The values computed depend on the <dfn>keyframe spacing mode</dfn>
specified for the <a>keyframe animation effect</a>.
The keyframe spacing modes are:

:   <dfn title="distribute keyframe spacing mode">distribute</dfn></dt>
::  Indicates that <a>keyframes</a> with a null <a>keyframe offset</a>
    null are positioned so that the difference between subsequent
    <a>keyframe offsets</a> are equal.
:   <dfn title="paced keyframe spacing mode">paced</dfn></dt>
::  Indicates that <a>keyframes</a> with a null <a>keyframe offset</a>
    null are positioned so that the <em>distance</em> between subsequent
    values of a specified <dfn>paced property</dfn> are equal.
    The distance is calculated using the <a>distance computation</a>
    procedure defined by the <a>animation behavior</a> associated
    with the <a>paced property</a>.

<h5 id="applying-spacing-to-keyframes">Applying spacing to keyframes</h5>

We define a generic procedure for <dfn>evenly distributing
a keyframe</dfn>, <var>keyframe</var>, between two reference
keyframes, <var>start</var> and <var>end</var>, whose <a>keyframe
offsets</a> are <em>not</em> null, as follows:

1.  Let <dfn>offset<sub><var>k</var></sub></dfn> be the <a>keyframe
    offset</a> of a <a>keyframe</a> <var>k</var>.
2.  Let <var>n</var> be the number of keyframes <em>between</em> and
    including <var>start</var> and <var>end</var> minus 1.
3.  Let <var>index</var> refer to the position of
    <var>keyframe</var> in the sequence of keyframes between
    <var>start</var> and <var>end</var> such that the first keyframe
    after <var>start</var> has an <var>index</var> of 1.
4.  Set the <a>keyframe offset</a> of <var>keyframe</var> to
    <a title="offsetk">offset</a><sub><var>start</var></sub> +
    (<a title="offsetk">offset</a><sub><var>end</var></sub> &minus;
     <a title="offsetk">offset</a><sub><var>start</var></sub>)
    &times; <var>index</var> / <var>n</var>.

The computed <a>keyframe offset</a> values of each <a>keyframe</a>
with a null keyframe offset are determined using the following
procedure.

1.  Let <var>keyframes</var> refer to the list of <a>keyframes</a>
    associated with the <a>keyframe animation effect</a>.
2.  If <var>keyframes</var> contains more than one
    <a>keyframe</a> and the <a>keyframe offset</a> of
    the first <a>keyframe</a> in <var>keyframes</var> is null,
    set the <a>keyframe offset</a> of
    the first <a>keyframe</a> to 0.
3.  If the <a>keyframe offset</a> of the last <a>keyframe</a> in
    <var>distributed keyframes</var> is null, set its
    <a>keyframe offset</a> to 1.
4.  For each pair of <a>keyframes</a> <var>A</var> and <var>B</var>
    where:

    *   <var>A</var> appears before <var>B</var> in
        <var>keyframes</var>, and
    *   <var>A</var> and <var>B</var> have a <a>keyframe
        offset</a> that is not null, and
    *   all <a>keyframes</a> between <var>A</var> and <var>B</var>
        have a null <a>keyframe offset</a>,

    calculate the <a>keyframe offset</a> of
    each <a>keyframe</a> between <var>A</var> and <var>B</var>
    depending on the <a>keyframe spacing mode</a> as follows:

    <div class="switch">

    :   If the <a title="keyframe spacing mode">spacing mode</a>
        is <a title="paced keyframe spacing mode">paced</a>,</dt>
    ::

        1.  Define a keyframe as <dfn>paceable</dfn> if it
            contains a value for the <a>paced property</a>.
        2.  Let <var>paced A</var> be the first keyframe in the
            range [<var>A</var>, <var>B</var>] that is
            <a>paceable</a>, if any.
        3.  Let <var>paced B</var> be the last keyframe in the
            range [<var>A</var>, <var>B</var>] that is
            <a>paceable</a>, if any.
        4.  If there is no <var>paced A</var> or <var>paced
            B</var> let both refer to <var>B</var>.

            Note: In this case the spacing behavior degenerates to <a
            title="distribute keyframe spacing mode">distribute</a> spacing.

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

            <div class="annotation">

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

            </div>

        6.  For each keyframe in the range
            (<var>paced A</var>, <var>paced B</var>) that is
            <a>paceable</a>:

            1.  Let
                <dfn title="distk">dist<sub><var>k</var></sub></dfn>
                represent the cumulative distance to a keyframe
                <var>k</var> from <var>paced A</var>
                as calculated by applying the <a>distance
                computation</a> defined by the <a>animation
                behavior</a> of the <a>paced property</a> to the
                values of the <a>paced property</a> on each pair of
                successive <a>paceable</a> keyframes in the range
                [<var>paced A</var>, <var>k</var>].
            2.  Set the offset of <var>k</var> to
                <a title="offsetk">offset</a><sub><var>paced
                  A</var></sub> +
                (<a title="offsetk">offset</a><sub><var>paced
                  B</var></sub> &minus;
                <a title="offsetk">offset</a><sub><var>paced
                  A</var></sub>) &times;
                <a title="distk">dist</a><sub><var>k</var></sub> /
                <a title="distk">dist</a><sub><var>paced
                  B</var></sub>
        7.  For each keyframe in the range (<var>paced A</var>,
            <var>paced B</var>) that still has
            a null <a>keyframe offset</a> (because it is not
            <a>paceable</a>), apply the procedure
            for <a>evenly distributing a keyframe</a> using
            the nearest <a>keyframe</a> before and after the
            keyframe in question in <var>keyframes</var> that has
            a <a>keyframe offset</a> that is not null, as the
            <var>start</var> and <var>end</var> keyframes
            respectively.
    :   Otherwise,</dt>
    ::  Apply the procedure for <a>evenly distributing
        a keyframe</a> to each keyframe in the range (<var>A</var>,
        <var>B</var>) using <var>A</var> and <var>B</var> as the
        <var>start</var> and <var>end</var> keyframes respectively.

    </div>

Note: although the above procedure defines computing keyframe
    offsets in terms of overwriting null values, user agents that
    implement the <a href="#programming-interface">programming
    interface</a> are required to maintain the original null values as
    well as calculating the computed offsets.
    This is because the {{KeyframeEffect/getFrames()}} method of the
    {{KeyframeEffect}} interface returns keyframe offsets both
    before and after applying spacing.

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

<h4 id="the-intermediate-animation-value-of-a-keyframe-animation-effect">The intermediate animation value of a keyframe animation effect</h4>

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

1.  Let <var>target property</var> be the property for which the
    <a>intermediate animation value</a> is to be calculated.
2.  If <a>animation behavior</a> of the <var>target property</var> is
    <a>not animatable</a> abort this procedure
    since the effect cannot be applied.
3.  Define the <dfn>neutral value for composition</dfn> as a value
    which, when combined with an <a>underlying value</a> using the <a
    title="composite operation add">add</a> <a>composite
    operation</a>, produces the <a>underlying value</a>.
4.  Let <var>property-specific keyframes</var> be a copy of the list
    of <a>keyframes</a> specified on the effect.
5.  Remove any <a>keyframes</a> from <var>property-specific
    keyframes</var> that do not have a property value for
    <var>target property</var>.
6.  If <var>property-specific keyframes</var> is empty, return
    <var>underlying value</var>.
7.  If there is no <a>keyframe</a> in <var>property-specific
    keyframes</var> with a <a>keyframe offset</a> of
    0, create a new <a>keyframe</a> with a <a>keyframe offset</a> of
    0, a property value set to the <a>neutral value for
    composition</a>, and a <a>composite operation</a> of <a
    title="composite operation add">add</a>, and prepend it to the
    beginning of <var>property-specific keyframes</var>.
8.  Similarly, if there is no <a>keyframe</a> in
    <var>property-specific keyframes</var> with a <a>keyframe
    offset</a> of 1,
    create a new <a>keyframe</a> with a <a>keyframe offset</a> of 1,
    a property value set to the <a>neutral value for composition</a>,
    and a <a>composite operation</a> of <a
    title="composite operation add">add</a>, and append it to the
    end of <var>property-specific keyframes</var>.
9.  Let <var>interval endpoints</var> be an empty sequence of
    keyframes.
10. Populate <var>interval points</var> by following the steps from
    the first matching condition from below:

    <div class="switch">

    :   If <var>time fraction</var> &lt; 0 and there is more
        than one <a>keyframe</a> in <var>property-specific
        keyframes</var> with a <a>keyframe offset</a> of
        0,
    ::  Add the first <a>keyframe</a> in <var>property-specific
        keyframes</var> to <var>interval endpoints</var>.
    :   If <var>time fraction</var> &ge; 1 and there is more
        than one <a>keyframe</a> in <var>property-specific
        keyframes</var> with a <a>keyframe offset</a> of
        1,
    ::  Add the last <a>keyframe</a> in <var>property-specific
        keyframes</var> to <var>interval endpoints</var>.
    :   Otherwise,
    ::

        1.  Append to <var>interval endpoints</var> the last
            <a>keyframe</a> in <var>property-specific
            keyframes</var> whose <a>keyframe offset</a> is less than
            or equal to <var>time fraction</var> and less than 1.  If
            there is no such <a>keyframe</a> (because, for example,
            the <a>time fraction</a> is negative), add the last
            <a>keyframe</a> whose <a>keyframe offset</a> is 0.
        2.  Append to <var>interval endpoints</var> the next
            <a>keyframe</a> in <var>property-specific keyframes</var>
            after the one added in the previous step.

    </div>

11. For each <var>keyframe</var> in <var>interval endpoints</var>:

    1.  If <var>keyframe</var> has a <a>composite operation</a>
        that is <em>not</em> <a
        title="composite operation replace">replace</a>, or
        <var>keyframe</var> has no <a>composite operation</a>
        and the <a>composite operation</a> of this <a>keyframe
        animation effect</a> is <em>not</em> <a
        title="composite operation replace">replace</a>, then
        perform the following steps:

        1.  Let <var>composite operation to use</var> be the
            <a>composite operation</a> of <var>keyframe</var>, or if
            it has none, the <a>composite operation</a> of this
            <a>keyframe animation effect</a>.
        2.  Let <var>value to combine</var> be the property value of
            <var>target property</var> specified on
            <var>keyframe</var>.
        3.  Replace the property value of <var>target property</var>
            on <var>keyframe</var> with the result of combining
            <var>underlying value</var> (<var>V</var><sub>a</sub>) and
            <var>value to combine</var> (<var>V</var><sub>b</sub>)
            using the <var>composite operation to use</var>
            procedure defined by the <var>target property</var>'s
            <a>animation behavior</a>.

    2.  If this <a>keyframe animation effect</a> has an <a>iteration
        composite operation</a> of <a
        title="iteration composite operation accumulate">accumulate</a>,
        apply the following step <var>current iteration</var> times:

        *   replace the property value of <var>target property</var>
            on <var>keyframe</var> with the result of combining the
            property value (<var>V</var><sub>a</sub>) with the
            property value on the final keyframe in
            <var>property-specific keyframes</var>
            (<var>V</var><sub>b</sub>) using the <a
            title="animation accumulation">accumulation procedure</a>
            defined for <var>target property</var>.

        Issue: 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 <var>interval endpoints</var>
    return the property value of <var>target property</var> on that
    keyframe.
13. Let <var>start offset</var> be the <a>keyframe offset</a> of the
    first keyframe in <var>interval endpoints</var>.
14. Let <var>end offset</var> be the <a>keyframe offset</a> of
    last keyframe in <var>interval endpoints</var>.
15. Let <var>interval distance</var> be the result of evaluating
    <code>(<var>time fraction</var> - <var>start offset</var>) /
    (<var>end offset</var> - <var>start offset</var>)</code>
16. Return the result of applying the <a
    title="animation interpolation">interpolation procedure</a> defined
    by the <a>animation behavior</a> of the <var>target property</var>,
    to the values of the <var>target property</var> specified on the
    two keyframes in <var>interval endpoints</var> taking the first such
    value as <var>V</var><sub>start</sub> and the second as
    <var>V</var><sub>end</sub> and using <var>interval
    distance</var> as the interpolation parameter <var>p</var>.

<div class="note">

    Note that this procedure assumes the following about the list of
    <a>keyframes</a> specified on the effect:</p>

    *   Each <a>keyframe</a> has a specified <a>keyframe offset</a> in
        the range [0, 1].
    *   The list of <a>keyframes</a> is sorted in ascending order by
        <a>keyframe offset</a>.
    *   Each specified property value is a valid and supported value.
    *   For a given property, there is a most one specified property
        value on each keyframe.

    It is the responsibility of the user of the model (for example,
    a declarative markup or programming interface) to ensure these
    conditions are met.

    For example, for the <a href="#programming-interface">programming
    interface</a> defined by this specification, these conditions are
    met by applying the normalization defined in <a
    href="#normalizing-a-sequence-of-keyframes" section></a>
    and resolving null <a>keyframe offsets</a> by
    applying <a href="#spacing-keyframes">spacing behavior</a>.

</div>

Note: this procedure permits overlapping <a>keyframes</a>.
    The behavior is that at the point of overlap the output value jumps to
    the value of the last defined <a>keyframe</a> at that offset.
    For overlapping frames at 0 or 1, the output value for <a
    title="time fraction">time fractions</a> less than 0 or greater than
    or equal to 1 is the value of the first <a>keyframe</a> or the last
    <a>keyframe</a> in <var>keyframes</var> respectively.

<div class="issue">
    In the presence of certain timing functions, the input time
    fraction to an animation effect is not limited to the range [0, 1].
    Currently, however, keyframe offsets <em>are</em> limited to the
    range [0, 1] and property values are simply extrapolated for input
    time fractions outside this range.

    We have considered removing this restriction since some cases exist
    where it is useful to be able to specify non-linear
    changes in property values at time fractions outside the range
    [0, 1].
    One example is an animation that interpolates from green to yellow
    but has an overshoot timing function that makes it temporarily
    interpolate &lsquo;beyond&rsquo; yellow to red before settling back
    to yellow.

    While this effect could be achieved by modification of the keyframes
    and timing function, this approach seems to break the model's
    separation of timing concerns from animation effects.

    It is not clear how this effect should be achieved but we note that
    allowing keyframe offsets outside [0, 1] may make the currently
    specified behavior where keyframes at offset 0 and 1 are synthesized
    as necessary, inconsistent.

    See <a
    href='http://lists.w3.org/Archives/Public/public-fx/2013AprJun/0184.html'>section
    4 (Keyframe offsets outside [0, 1]) of minuted discussion from Tokyo
      2013 F2F</a>.
</div>

<h3 id="custom-effects">Custom effects</h3>

<div class='informative-bg'><em>This section is non-normative</em>

In some situations the <a>animation
effects</a> provided by Web Animations may be insufficient.
For example, the <a>animation effects</a>
defined here are only able to target certain CSS properties.
They are unable, therefore, to modify the <a
href="http://www.w3.org/TR/SVG11/struct.html#__svg__SVGSVGElement__currentScale"><code>currentScale</code></a>
property of an SVG element to smoothly zoom the viewport without
affecting the document content.

In such cases, where the provided <a>animation
effects</a> do not provide needed functionality, an effect defined by
script may be used.
Such <a>custom effects</a> receive a <a>time
fraction</a> and <a>current iteration</a> from the timing model and
are responsible for producing an effect corresponding to the specified
time.

Using an effect defined in script it is possible to animate not only
otherwise un-animatable attributes and properties, but potentially
anything that is accessible via script, including even producing audio
or creating vibrations.

For example, using a <a>custom effect</a> that draws to a <a
href="http://www.w3.org/TR/html5/scripting-1.html#the-canvas-element"><code>canvas</code></a>
element, it is possible to produce a complex animated effect
featuring patterns that may be difficult to create using CSS or
SVG.
Compared to using <a
href="http://www.w3.org/TR/animation-timing/">Timing control for
script-based animations</a>,
this approach ensures the animation is frame-rate
independent and can be paused, reversed, eased with timing effects,
accelerated, synchronized with other animations, and be controlled
in the same manner as any other Web Animations animation without any
additional programming.

</div>

A <dfn>custom effect</dfn> is an author-defined programming callback
that is passed timing information when <a>sampling</a> is performed.

<h4 id="sampling-custom-effects">Sampling custom effects</h4>

<a>Custom effects</a> are called for each referencing <a>animation</a>
when a <a title='single-sample'>sample</a> is performed based on the 
following criteria.

1.  If, on the previous sample, the <a>animation</a>
    referencing the <a>custom effect</a>:

    *   was <a>in effect</a>, and
    *   referenced this same <a>custom effect</a>, and
    *   had a different <a>animation target</a>

    Call the callback passing an <a>unresolved</a> <a>time fraction</a> and
    the <a>animation target</a> from the previous sample as parameters to
    the callback.
2.  Call the callback for the current <a>animation target</a> based on
    the first matching condition from the following:

    <div class="switch">

    :   If the <a>animation</a> referencing the custom
        effect is not <a>in effect</a> but was <a>in effect</a> in the previous
        sample,
    ::  Call the callback passing an <a>unresolved</a> <a>time fraction</a> and
        the current <a>animation target</a> as parameters to the callback.
    :   Otherwise, if the <a>animation</a> referencing
        the custom effect:
    ::

        *   <strong>is <a>in effect</a>, and</strong>
        *   <strong>was not <a>in effect</a> in the previous 
            <a title='single-sample'>sample</a>, or
              was <a>in effect</a> but with a different <a>time
              fraction</a> or <a>current iteration</a>,</strong>

    ::   Call the callback passing with the referencing
        <a>animation</a>'s current <a>time
        fraction</a> and <a>animation target</a> as parameters to the callback.

    </div>

<div class="issue">
There may be use cases where an action needs to be triggered at
a specific point in an animation tree.
In many cases this can be achieved by inserting a custom effect with
a step-start easing that spans the period during which the action
should be triggered.
However, this can impose additional layout requirements on the
content which might be cumbersome to accomodate.

Some alternatives under consideration:

*   Additional calling conditions could be defined to accommodate
    zero-width custom effects. For example, it could be required
    that the callback be called if (given infinite precision) there
    was a time between the previous and current sample times that
    aligned with the custom effect.
*   Instead of adding special calling conditions to custom effects,
    a new type of animation node, Trigger, could be introduced. The
    trigger would only ever act as a zero-width custom effect as
    described above, its constructor would take a callback function,
    but not require a target or timing. It could also specify other
    calling conventions, for example whether it should only trigger
    in a specific playback direction.

</div>

<h4 id="execution-order-of-custom-effects">Execution order of custom effects</h4>

Since <a>custom effects</a>, unlike <a
title="animation effect">animation effects</a>, are not limited to
a single <a>target property</a>, the steps for assessing their
order of execution differs from <a>animation effects</a>.f

<a>Custom effects</a> are executed after all
<a>animation effects</a> have completed and
applied their result to their targets (see <a
href="#applying-the-composited-result" section></a>).

Issue: 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 <a>custom effects</a>, the
order of execution is the same as that defined for <a title="animation
effect">animation effects</a> in <a href="#the-animation-stack" section></a>.
Items sorted earlier are executed before those sorted later.

<!-- End of animation model -->

<h2 id="programming-interface">Programming interface</h2>

<div class='informative-bg'><em>This section is non-normative</em>

In addition to the abstract model described above, Web Animations also
defines a programming interface to the model.
This interface can be used to inspect and extend animations produced
by declarative means or for directly producing animations when
a procedural approach is more suitable.

</div>

<h3 id='time-values-in-the-programming-interface'>
Time values in the programming interface</h3>

<a>Time values</a> are represented in the programming interface with
the type <code>double</code>. <a>Unresolved</a> time values are
represented by the value <code>null</code>.

<h3 id="the-animationtimeline-interface">The <code>AnimationTimeline</code> interface</h3>

<a>Timelines</a>, including the <a>document
timeline</a> are represented in the Web Animations API by the
{{AnimationTimeline}} interface.

<pre class="idl">
interface AnimationTimeline {
    readonly attribute double? currentTime;
    AnimationPlayer           play (optional AnimationNode? source = null);
    sequence&lt;AnimationPlayer&gt; getAnimationPlayers ();
};
</pre>

<div class='attributes'>

:   <dfn attribute for=AnimationTimeline>currentTime</dfn>
::  Returns the <a>time value</a> for this timeline or <code>null</code>
    if this timeline is <a title="inactive timeline">inactive</a>.

</div>

<div class='methods'>

:   <dfn method for=AnimationTimeline title='play()'>
    AnimationPlayer play(optional AnimationNode? source = null)</dfn>
::  Creates a new {{AnimationPlayer}} object associated with
    this <a>timeline</a> that begins playback as soon as it is
    <a>ready</a>.

    If <var>source</var> is specified, it will be used as the player's <a>source
    content</a>.

    Issue: Need to define the start behavior when <var>source</var> is null.

    The new {{AnimationPlayer}} object is created using the <a 
    constructor for="AnimationPlayer" title="AnimationPlayer()">the
    AnimationPlayer constructor</a> passing this
    {{AnimationTimeline}} object as the <var>timeline</var> parameter and
    <var>source</var> as the <var>source</var> parameter.

    Following construction of the {{AnimationPlayer}} object, the procedure to
    <a>play a player</a> is performed on the newly constructed object.

    <div class='parameters'>

    :   source
    ::  the <a>source content</a> to assign to the newly-created
        {{AnimationPlayer}} object.

    </div>

:   <dfn method for=AnimationTimeline title='getAnimationPlayers()'>
    sequence&lt;AnimationPlayer&gt; getAnimationPlayers()</dfn>
::  Returns the set of {{AnimationPlayer}} objects
    associated with this <a>timeline</a> that have associated
    <a>source content</a> which is <a>current</a> or <a>in effect</a>.

    The returned list is sorted in increasing order by <a>player
    sequence number</a>.

    The returned list reflects the state <em>after</em> applying any pending
    changes to animation such as changes to animation-related style properties
    that have yet to be processed.

    Issue: Both this method and {{Animatable/getAnimationPlayers()}} on the
           {{Animatable}} interface require retaining forwards-filling
           <a>animations</a> and their <a>players</a>
           such that a document that
           repeatedly produces forwards-filling animations will consume memory
           in an unbounded fashion.
           We may need to revise this definition (previously these methods
           only returned players whose <a>source content</a> was <a>current</a>)
           or provide a loophole for implementations to discard old players in
           such conditions.

<h3 id="the-animationplayer-interface">The <code>AnimationPlayer</code> interface</h3>

<a>Players</a> are represented in the Web Animations
API by the {{AnimationPlayer}} interface.

<pre class='idl'>
[Constructor (optional AnimationNode? source = null,
              optional AnimationTimeline? timeline = null)]
interface AnimationPlayer {
             attribute AnimationNode?           source;
             attribute AnimationTimeline?       timeline;
             attribute double?                  startTime;
             attribute double?                  currentTime;
             attribute double                   playbackRate;
    readonly attribute AnimationPlayState       playState;
    readonly attribute Promise&lt;AnimationPlayer&gt; ready;
    readonly attribute Promise&lt;AnimationPlayer&gt; finished;
    void cancel ();
    void finish ();
    void play ();
    void pause ();
    void reverse ();
};
</pre>

<div class="constructors">

:   <dfn constructor for=AnimationPlayer title="AnimationPlayer()">
:   Constructor ()</dfn>
::  Creates a new {{AnimationPlayer}} object using the following procedure.

    1.  Let <var>player</var> be a new {{AnimationPlayer}} object.
    2.  Run the procedure to <a>set the timeline of a player</a> on
        <var>player</var> passing <var>timeline</var> as the <var>new
        timeline</var>.
    3.  Run the procedure to <a>set the source content of a player</a> on
        <var>player</var> passing <var>source</var> as the <var>new
        content</var>.

    <div class="parameters">

    :   source
    ::  An optional value which, if not null, specifies the <a>source
        content</a> to assign to the newly created <a>player</a>.

    :   timeline
    ::  An optional value which, if not null, specifies the <a>timeline</a>
        with which to associate the newly created <a>player</a>.

    </div>

</div>

<div class='attributes'>

:   <dfn attribute for=AnimationPlayer>source</dfn>
::  The <a>source content</a> associated with this player.
    Setting this attribute updates the object's <a>source content</a> using
    the procedure to <a>set the source content of a player</a>.
:   <dfn attribute for=AnimationPlayer>timeline</dfn>
::  The <a>timeline</a> associated with this player.
    Setting this attribute updates the object's <a>timeline</a> using
    the procedure to <a>set the timeline of a player</a>.
:   <dfn attribute for=AnimationPlayer>startTime</dfn>
::  Returns the <a title="player start time">start time</a> of this
    player.
    Setting this attribute updates the <a>player start time</a> using
    the procedure to <a>update the player start time</a> of this object
    to the new value.
:   <dfn attribute for=AnimationPlayer>currentTime</dfn>
::  The <a>current time</a> of this player unless
    this player has a <a>pending pause task</a>, in which case
    this attribute returns <code>null</code>.

    Issue: This behavior is intended to prevent authors for relying
    on the <code>currentTime</code> while a player is waiting to pause
    but is also somewhat confusing.

    Setting this attribute follows the procedure to <a>set the current time</a>
    of this object to the new value.
:   <dfn attribute for=AnimationPlayer>playbackRate</dfn>
::  The <a title="player playback rate">playback rate</a> of this
    player.
    Setting this attribute follows the procedure to <a>update the player
    playback rate</a> of this object to the new value.
:   <dfn attribute for=AnimationPlayer>playState</dfn>
::  The <a>play state</a> of this player.
:   <dfn attribute for=AnimationPlayer>ready</dfn>
::  Returns the <a>current ready promise</a> for this object.
:   <dfn attribute for=AnimationPlayer>finished</dfn>
::  Returns the <a>current finished promise</a> for this object.

</div>

<div class='methods'>

:   <dfn method for=AnimationPlayer title='cancel()'>void cancel()</dfn>
::  Clears all effects caused by this player and aborts its playback
    by running the <a>cancel a player</a> procedure for this object.
:   <dfn method for=AnimationPlayer title='finish()'>void finish()</dfn>
::  Seeks the player to the end of the <a>source content</a> in the
    current direction by running the <a>finish a player</a> procedure
    for this object.

    <div class='exceptions'>

    :   DOMException of type <code>InvalidStateError</code>
    ::  Raised if this player's <a title="player playback rate">playback
        rate</a> is zero, or if this player's <a
        title="player playback rate">playback rate</a> is &gt; zero and the
        <a>end time</a> of this player's <a>source content</a> is infinity.

    </div>

:   <dfn method for=AnimationPlayer title='play()'>void play()</dfn>
::  Unpauses the player and rewinds if it has finished playing using
    the procedure to <a>play a player</a> for this object.
:   <dfn method for=AnimationPlayer title='pause()'>void pause()</dfn>
::  Suspends the playback of this player by running the procedure to
    <a>pause a player</a> for this object.
:   <dfn method for=AnimationPlayer title='reverse()'>void reverse()</dfn>
::  Inverts the <a title="player playback rate">playback rate</a> of
    this player and plays it using the <a>reverse a player</a> procedure for
    this object.
    As with <a method for=AnimationPlayer title="play()">play()</a>, this
    method unpauses the player and, if the player has already finished playing
    in the reversed direction, seeks to the start of the <a>source content</a>.

</div>

<h4 id="the-animationplaystate-enumeration">The <code>AnimationPlayState</code> enumeration</h4>

<pre class='idl'>enum AnimationPlayState { "idle", "pending", "running", "paused", "finished" };</pre>

:   <code>idle</code>
::  Corresponds to the <a>idle play state</a>.
:   <code>pending</code>
::  Corresponds to the <a>pending play state</a>.
:   <code>running</code>
::  Corresponds to the <a>running play state</a>.
:   <code>paused</code>
::  Corresponds to the <a>paused play state</a>.
:   <code>finished</code>
::  Corresponds to the <a>finished play state</a>.

<h3 id="the-animationnode-interface">The <code>AnimationNode</code> interface</h3>

<a>Animation nodes</a> are represented in the Web
Animations API by the {{AnimationNode}} interface.

<pre class='idl'>
interface AnimationNode {
    // Timing
    readonly attribute AnimationTiming          timing;
    readonly attribute ComputedTimingProperties computedTiming;

    // Timing hierarchy
    readonly attribute AnimationGroup?          parent;
    readonly attribute AnimationNode?           previousSibling;
    readonly attribute AnimationNode?           nextSibling;
    void before (AnimationNode... nodes);
    void after (AnimationNode... nodes);
    void replace (AnimationNode... nodes);
    void remove ();
};
</pre>

<div class='attributes'>

:   <dfn attribute for=AnimationNode>timing</dfn>
::  Returns the input timing properties specified for this
    <a>animation node</a>.
    This is comparable to the specified style on an Element,
    <code>elem.style</code>.
:   <dfn attribute for=AnimationNode>computedTiming</dfn>
::  Returns the calculated timing properties for this <a>animation
    node</a>.
    This is comparable to the computed style of an Element,
    <code>window.getComputedStyle(elem)</code>.

    Although several of the attributes of the this object are common
    to the {{AnimationTiming}} object returned by the {{AnimationNode/timing}}
    attribute, the values of this object represent the values <em>after</em>
    applying the adjustments described by the {{AnimationTiming}} interface as
    being <cite>&ldquo;for the purpose of timing model
    calculations&rdquo;</cite>.

    <code>auto</code> values are also expanded as follows:

    *   <code>duration</code> &ndash; returns the calculated value of
        the <a>iteration duration</a>. If <code>timing.duration</code>
        is the string <code>auto</code> or any unsupported value, this
        attribute will return the current calculated value of the
        <a>intrinsic iteration duration</a>.
    *   <code>fill</code> &ndash; the <code>auto</code> value is
        replaced with the specific <a enum>FillMode</a> depending on the type
        of <a>animation node</a> (see <a
        href="#the-fillmode-enumeration" section></a>).

:   <dfn attribute for=AnimationNode>parent</dfn>
::  The <a>parent animation group</a> of this <a>animation node</a> or
    <code>null</code> if this <a>animation node</a> does not have
    a <a>parent animation group</a>.

    Issue: Should this be <code>parentGroup</code>?

:   <dfn attribute for=AnimationNode>previousSibling</dfn>
::  The <a>previous sibling</a> of this <a>animation node</a>.
:   <dfn attribute for=AnimationNode>nextSibling</dfn>
::  The <a>next sibling</a> of this <a>animation node</a>.

</div>

<div class='methods'>

:   <dfn method for=AnimationNode title='before()'>
    void before (AnimationNode... nodes)</dfn>
::  Inserts <var>nodes</var> before this <a>animation node</a>.

    1.  If there is no <a>parent animation group</a>, terminate these
        steps.
    2.  If any of the <a>animation nodes</a> in <var>nodes</var> is an
        <a>inclusive ancestor</a> of this <a>animation node</a>
        throw a <code>HierarchyRequestError</code> exception and
        terminate these steps.
    3.  <a title="insert children">Insert</a> <var>nodes</var> before
        this <a>animation node</a>.

    <div class='note'>
        Note that this definition precludes the following usage since
        <code>node</code> is an <a>inclusive ancestor</a> of itself:

        <div><pre class="example sh_javascript">
        node.before(node); // throws HierarchyRequestError
        </pre></div>
    </div>

:   <dfn method for=AnimationNode title='after()'>
    void after(AnimationNode... nodes)</dfn>
::  Inserts <var>nodes</var> after this <a>animation node</a>.

    1.  If there is no <a>parent animation group</a>, terminate these
        steps.
    2.  If any of the <a>animation nodes</a> in <var>nodes</var> is an
        <a>inclusive ancestor</a> of this <a>animation node</a>
        throw a <code>HierarchyRequestError</code> exception and
        terminate these steps.
    3.  Let <var>reference child</var> be the <a
        title="next sibling not included">next sibling of
        this animation node not in <var>nodes</var></a>.
    4.  <a title="insert children">Insert</a> <var>nodes</var> before
        <var>reference child</var>.

:   <dfn method for=AnimationNode title='replace()'>
    void replace(AnimationNode... nodes)</dfn>
::  Replaces this {{AnimationNode}} with the passed in
    <var>nodes</var>.

    1.  If there is no <a>parent animation group</a>, terminate these
        steps.
    2.  If any of the <a>animation nodes</a> in <var>nodes</var> is an
        <a>inclusive ancestor</a> of the <a>parent animation group</a>
        throw a <code>HierarchyRequestError</code> exception and
        terminate these steps.
    3.  Let <var>reference child</var> be the <a
        title="next sibling not included">next sibling of
        this animation node not in <var>nodes</var></a>.
    4.  <a title="remove an animation node">Remove</a> this
        <a>animation node</a> from its <a>parent animation group</a>.
    5.  <a title="insert children">Insert</a> <var>nodes</var> before
        <var>reference child</var>.

:   <dfn method for=AnimationNode title='remove()'>void remove()</dfn>
::  <a title="remove an animation node">Removes</a> this <a>animation
    node</a> from its <a>parent animation group</a> or <a>player</a>.

</div>


<h3 id="the-animationtimingreadonly-interface">The <code>AnimationTimingReadOnly</code> interface</h3>

<pre class="idl">interface AnimationTimingReadOnly {
    readonly attribute double                             delay;
    readonly attribute double                             endDelay;
    readonly attribute FillMode                           fill;
    readonly attribute double                             iterationStart;
    readonly attribute unrestricted double                iterations;
    readonly attribute (unrestricted double or DOMString) duration;
    readonly attribute double                             playbackRate;
    readonly attribute PlaybackDirection                  direction;
    readonly attribute DOMString                          easing;
};
</pre>

<div class="attributes">

:   <dfn attribute for=AnimationTimingReadOnly>delay</dfn>
::  The <a>start delay</a> which represents the number of milliseconds
    from an <a>animation node</a>'s <a title="animation node start time">start
    time</a> to the start of the <a>active interval</a>.

    Issue: Now that we have <code>endDelay</code>, should we change this back
        to <code>startDelay</code>?

:   <dfn attribute for=AnimationTimingReadOnly>endDelay</dfn>
::  The <a>end delay</a> which represents the number of milliseconds
    from the end of an <a>animation node</a>'s <a>active interval</a>
    until the <a title='animation node start time'>start time</a> of any
    <a>animation node</a> that may
    follow, for example, in an <a>animation sequence</a>.

:   <dfn attribute for=AnimationTimingReadOnly>fill</dfn>
::  The <a>fill mode</a> as specified by one of the <a enum>FillMode</a>
    enumeration values.

    When performing timing calculations the special value <span
    class="prop-value">auto</span> is expanded
    to one of the <a>fill modes</a> recognized by the timing model as
    follows,

    <div class="switch">

    :   If the <a>animation node</a> to which the fill mode is being is
        applied is an <a>animation</a>,
    ::  Use <span class="prop-value">none</span> as the <a>fill
        mode</a>.
    :   Otherwise,
    ::  Use <span class="prop-value">both</span> as the <a>fill
        mode</a>.

    </div>

:   <dfn attribute for=AnimationTimingReadOnly>iterationStart</dfn>
::  The <a>animation node</a>'s <a>iteration start</a> property.

    A finite real number greater than or equal to zero representing
    the number of iterations into the animation node at which to
    begin.

:   <dfn attribute for=AnimationTimingReadOnly>iterations</dfn>
::  The <a>animation node</a>'s <a>iteration count</a> property.

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

:   <dfn attribute for=AnimationTimingReadOnly>duration</dfn>
::  The <a>iteration duration</a> 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 <a>animation
    node</a>.

    The string value <code>auto</code> is used to indicate that the
    <a>iteration duration</a> reflects the animation node's
    <a>intrinsic iteration duration</a>.

:   <dfn attribute for=AnimationTimingReadOnly>playbackRate</dfn>
::  The <a>animation node</a>'s <a
    title="animation node playback rate">playback rate</a> property.

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

:   <dfn attribute for=AnimationTimingReadOnly>direction</dfn>
::  The <a>playback direction</a> of the <a>animation node</a> as
    specified by one of the <a enum>PlaybackDirection</a> enumeration
    values.

:   <dfn attribute for=AnimationTimingReadOnly>easing</dfn>
::  The <a>timing function</a> used to scale the time to
    produce easing effects.

    The syntax of the string is defined by the following production:
    <blockquote>
      <div class="production">
        "linear"
          | <a>&lt;cubic-bezier-timing-function&gt;</a>
          | <a>&lt;step-timing-function&gt;</a>
      </div>
    </blockquote>

    <div class="annotation">
      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
      <code>easingList</code> similar to HTML's <code>classList</code>.
    </div>

</div>

<h3 id="the-animationtiming-interface">The <code>AnimationTiming</code> interface</h3>

The {{AnimationTiming}} interface is a writeable subclass of
{{AnimationTimingReadOnly}} used for an {{AnimationNode}}'s
<code>timing</code> attribute.

<pre class='idl'>
interface AnimationTiming : AnimationTimingReadOnly {
    inherit attribute double                             delay;
    inherit attribute double                             endDelay;
    inherit attribute FillMode                           fill;
    inherit attribute double                             iterationStart;
    inherit attribute unrestricted double                iterations;
    inherit attribute (unrestricted double or DOMString) duration;
    inherit attribute double                             playbackRate;
    inherit attribute PlaybackDirection                  direction;
    inherit attribute DOMString                          easing;
};
</pre>

<div class='attributes'>

:   <dfn attribute for=AnimationTiming>delay</dfn>
::  See the {{AnimationTimingReadOnly/delay}} attribute of the
    {{AnimationTimingReadOnly}} interface.
:   <dfn attribute for=AnimationTiming>endDelay</dfn>
::  See the {{AnimationTimingReadOnly/endDelay}} attribute of the
    {{AnimationTimingReadOnly}} interface.
:   <dfn attribute for=AnimationTiming>fill</dfn>
::  See the {{AnimationTimingReadOnly/fill}} attribute of the
    {{AnimationTimingReadOnly}} interface.
:   <dfn attribute for=AnimationTiming>iterationStart</dfn>
::  See the {{AnimationTimingReadOnly/iterationStart}} attribute of the
    {{AnimationTimingReadOnly}} interface.

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

    <div class="note">
    Note that the value of {{AnimationTiming/iterations}} is effectively
    <em>added</em> to the {{AnimationTiming/iterationStart}} such that
    an animation node with an {{AnimationTiming/iterationStart}} of
    &lsquo;0.5&rsquo; and {{AnimationTiming/iterations}} of
    &lsquo;2&rsquo; would still repeat twice however it would begin
    and end half-way through the animation node's <a>iteration
    interval</a>.

    Setting the {{AnimationTiming/iterationStart}} to a value greater than
    or equal to one is typically only useful in combination with an
    animation effect that has an <a>iteration composite
    operation</a> of &lsquo;accumulate&rsquo;.
    </div>


:   <dfn attribute for=AnimationTiming>iterations</dfn>
::  See the {{AnimationTimingReadOnly/iterations}} attribute of the
    {{AnimationTimingReadOnly}} interface.

    Values less than zero and <code>NaN</code> values are treated as
    the value 1.0 for the purpose of timing model calculations.
:   <dfn attribute for=AnimationTiming>duration</dfn>
::  See the {{AnimationTimingReadOnly/duration}} attribute of the
    {{AnimationTimingReadOnly}} interface.

    Real numbers less than zero, <code>NaN</code> values, and strings
    other than the lowercase value <code>auto</code> are treated
    the same as <code>auto</code> for the purpose of timing model
    calculations.
:   <dfn attribute for=AnimationTiming>playbackRate</dfn>
::  See the {{AnimationTimingReadOnly/playbackRate}} attribute of the
    {{AnimationTimingReadOnly}} interface.
:   <dfn attribute for=AnimationTiming>direction</dfn>
::  See the {{AnimationTimingReadOnly/direction}} attribute of the
    {{AnimationTimingReadOnly}} interface.
:   <dfn attribute for=AnimationTiming>easing</dfn>
::  See the {{AnimationTimingReadOnly/easing}} attribute of the
    {{AnimationTimingReadOnly}} interface.

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

</div>

<h3 id="the-computedanimationtiming-interface">The
  <code>ComputedTimingProperties</code> dictionary</h3>

Timing parameters calculated by the timing model are exposed using
{{ComputedTimingProperties}} dictionary objects.

<pre class='idl'>
dictionary ComputedTimingProperties : AnimationTimingProperties {
    double              startTime;
    unrestricted double endTime;
    unrestricted double activeDuration;
    double?             localTime;
    unrestricted double timeFraction;
    unsigned long?      currentIteration;
};</pre>

<div class='attributes'>

:   <dfn dict-member for=ComputedTimingProperties>startTime</dfn>
::  The <a title='animation node start time'>start time</a> of this
    <a>animation node</a> in milliseconds.
    This is the time at which the <a>parent animation group</a>, if
    any, has scheduled this child to run within its <a
    title="transformed time">transformed time space</a>, that is, the
    <a>animation node</a>'s <a title="inherited time">inherited time
    space</a>.

    The start of the <a>active interval</a> is based on the sum of
    the <a title="animation node start time">start time</a> and
    <a>start delay</a>.

:   <dfn dict-member for=ComputedTimingProperties>endTime</dfn>
::  The <a>end time</a> of the <a>animation node</a> expressed in
    milliseconds in <a title="inherited time">inherited time
    space</a>.
    This corresponds to the end of the <a>animation node</a>'s active
    interval plus any <a>end delay</a>.

:   <dfn dict-member for=ComputedTimingProperties>activeDuration</dfn>
::  The <a>active duration</a> of this <a>animation node</a>.

:   <dfn dict-member for=ComputedTimingProperties>localTime</dfn>
::  The <a>local time</a> of this <a>animation node</a>.

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

:   <dfn dict-member for=ComputedTimingProperties>timeFraction</dfn>
::  The current <a>time fraction</a> of this <a>animation node</a>.

:   <dfn dict-member for=ComputedTimingProperties>currentIteration</dfn>
::  The <a>current iteration</a> index beginning with zero for the first
    iteration.

    In the case where the <a>current iteration</a> index is infinity,
    (as can happen with a zero-duration animation that repeats infinite times),
    the return value to be used in ECMAScript is <code>Infinity</code>.
    The value for other language bindings is undefined.

</div>

<h3 id="the-animationtiminginput-dictionary">The <code>AnimationTimingProperties</code> dictionary</h3>

The {{AnimationTimingProperties}} dictionary is encapsulates the timing
properties of an {{AnimationNode}} so that they can be set in bulk (as in
the <a constructor for="Animation" title="Animation()">constructor for
Animation</a>) or returned as a readonly snapshot (as in
{{AnimationNode/computedTiming}}).

<pre class='idl'>
dictionary AnimationTimingProperties {
    double                             delay = 0;
    double                             endDelay = 0;
    FillMode                           fill = "auto";
    double                             iterationStart = 0.0;
    unrestricted double                iterations = 1.0;
    (unrestricted double or DOMString) duration = "auto";
    double                             playbackRate = 1.0;
    PlaybackDirection                  direction = "normal";
    DOMString                          easing = "linear";
};
</pre>

<div class='attributes'>

:   <dfn dict-member for=AnimationTimingProperties>delay</dfn>
::  The specified <a>start delay</a>.

    See the {{AnimationTiming/delay}} attribute of
    the {{AnimationTiming}} interface.

:   <dfn dict-member for=AnimationTimingProperties>endDelay</dfn>
::  The specified <a>end delay</a>.

    See the {{AnimationTiming/endDelay}} attribute of
    the {{AnimationTiming}} interface.

:   <dfn dict-member for=AnimationTimingProperties>fill</dfn>
::  The <a>fill mode</a> as specified by one of the <a enum>FillMode</a>
    enumeration values.

:   <dfn dict-member for=AnimationTimingProperties>iterationStart</dfn>
::  The <a>animation node</a>'s <a>iteration start</a> property.

    See the {{AnimationTiming/iterationStart}} attribute
    of the {{AnimationTiming}} interface.

:   <dfn dict-member for=AnimationTimingProperties>iterations</dfn>
::  The <a>animation node</a>'s <a>iteration count</a> property.

    See the {{AnimationTiming/iterations}} attribute
    of the {{AnimationTiming}} interface.

:   <dfn dict-member for=AnimationTimingProperties>duration</dfn>
::  The <a>iteration duration</a> of the <a>animation node</a>.

    See the {{AnimationTiming/duration}}
    attribute of the {{AnimationTiming}} interface.

:   <dfn dict-member for=AnimationTimingProperties>playbackRate</dfn>
::  The <a>animation node</a>'s <a
    title="animation node playback rate">playback rate</a> property.

    See the {{AnimationTiming/playbackRate}} attribute
    of the {{AnimationTiming}} interface.

:   <dfn dict-member for=AnimationTimingProperties>direction</dfn>
::  The <a>playback direction</a> of the <a>animation node</a>.

    See the {{AnimationTiming/direction}} attribute
    of the {{AnimationTiming}} interface.

:   <dfn dict-member for=AnimationTimingProperties>easing</dfn>
::  The <a>timing function</a> used to scale the time to produce
    easing effects.

    See the {{AnimationTiming/easing}} attribute
    of the {{AnimationTiming}} interface.

</div>

<h4 id="the-fillmode-enumeration">The <code>FillMode</code> enumeration</h4>

<pre class='idl'>enum FillMode { "none", "forwards", "backwards", "both", "auto" };</pre>

:   <code>none</code>
::  No fill.

:   <code>forwards</code>
::  Fill forwards.

:   <code>backwards</code>
::  Fill backwards.

:   <code>both</code>
::  Fill backwards and forwards.

:   <code>auto</code>
::  Fill backwards and forwards when applied to an
    {{AnimationGroup}} and no fill when applied to an
    {{Animation}}.


<h4 id="the-playbackdirection-enumeration">The <code>PlaybackDirection</code> enumeration</h4>

<pre class='idl'>enum PlaybackDirection { "normal", "reverse", "alternate", "alternate-reverse" };</pre>

:   <code>normal</code>
::  All iterations are played as specified.

:   <code>reverse</code>
::  All iterations are played in the reverse direction from the way
    they are specified.

:   <code>alternate</code>
::  Even iterations are played as specified, odd iterations are played
    in the reverse direction from the way they are specified.

:   <code>alternate-reverse</code>
::  Even iterations are played in the reverse direction from the way
    they are specified, odd iterations are played as specified.

<h3 id="the-animationgroup-interface">The <code>AnimationGroup</code> interface</h3>

<a>Animation groups</a> are represented by the {{AnimationGroup}}
interface.

<pre class='idl'>
[Constructor (sequence<AnimationNode>? children,
              optional (unrestricted double or AnimationTimingProperties) timing)]
interface AnimationGroup : AnimationNode {
    readonly attribute AnimationNodeList children;
    readonly attribute AnimationNode?    firstChild;
    readonly attribute AnimationNode?    lastChild;
    void           prepend (AnimationNode... nodes);
    void           append (AnimationNode... nodes);
    AnimationGroup clone ();
};</pre>

<div class="constructors">

:   <dfn constructor for=AnimationGroup title="AnimationGroup()">
:   Constructor ()</dfn>
::  Creates a new {{AnimationGroup}} object using the following
    procedure:

    1.  Create a new {{AnimationGroup}} object, <var>group</var>.
    2.  Set <var>timing input</var> as follows,

        <div class="switch">

        :   If <var>timing</var> is an {{AnimationTimingProperties}}
            object,
        ::  Let <var>timing input</var> refer to <var>timing</var>.

        :   If <var>timing</var> is a <code>double</code>,
        ::  Let <var>timing input</var> be a new
            {{AnimationTimingProperties}} object with all members set to
            their default values and <code>duration</code> set to
            <var>timing</var>.

        :   Otherwise (<var>timing</var> is undefined),
        ::  Let <var>timing input</var> be a new
            {{AnimationTimingProperties}} object with all members set to
            their default values.

        </div>

    3.  Set <code><var>group</var>.timing</code> to a new
        {{AnimationTiming}} object whose attributes are assigned the
        value of the member of the same name on <var>timing input</var>.

        <div class="todo">

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

        </div>

    4.  <a title="insert children">Insert</a> <var>children</var>
        before <code>null</code>.

    <div class="note">

    Note that since {{AnimationTiming}} objects have the same
    member names as {{AnimationTimingProperties}} dictionaries, it is
    also possible to pass the <code>timing</code> member of another
    {{AnimationNode}} as the <var>timing</var> parameter.

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

    </div>

    <div class="parameters">

    :   children
    ::  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 of the
        {{AnimationGroup}} interface.

    :   timing
    ::  The timing properties or <a>iteration duration</a> of the new
        animation group.

    </div>

</div>

<div class="attributes">

:   <dfn attribute for=AnimationGroup>children</dfn>
::  The list of <a>child animation nodes</a> in the group.

:   <dfn attribute for=AnimationGroup>firstChild</dfn>
::  The <a>first child</a> of this <a>animation group</a>.

:   <dfn attribute for=AnimationGroup>lastChild</dfn>
::  The <a>last child</a> of this <a>animation group</a>.

</div>

<div class="methods">

:   <dfn method for=AnimationTimeline title="prepend()">
:   void prepend (AnimationNode... nodes)</dfn>
::

    1.  If any of the <a>animation nodes</a> in <var>nodes</var> is an
        <a>inclusive ancestor</a> of this <a>animation node</a>
        throw a <code>HierarchyRequestError</code> exception and
        terminate these steps.
    2.  <a title="insert children">Insert</a> <var>nodes</var> before
        the <a>first child</a>.

:   <dfn method for=AnimationTimeline title="append()">
    void append (AnimationNode... nodes)</dfn>
::

    1.  If any of the <a>animation nodes</a> in <var>nodes</var> is an
        <a>inclusive ancestor</a> of this <a>animation node</a>
        throw a <code>HierarchyRequestError</code> exception and
        terminate these steps.
    2.  <a title="insert children">Insert</a> <var>nodes</var> before
        <code>null</code>.

:   <dfn method for=AnimationTimeline title="clone()">
    AnimationGroup clone ()</dfn>
::  Creates a deep copy of this {{AnimationGroup}} object using the
    following procedure.

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

</div>

<h4 id="definitions-for-manipulating-hierarchies">Definitions for manipulating hierarchies</h4>

The <dfn title="next sibling not included">next sibling of
<var>node</var> not included</dfn> in a set of <a>animation
nodes</a>, <var>nodes</var> is determined using the following
teps:</p>

1.  Let <var>context node</var> be <var>node</var>.
2.  While the <a>next sibling</a> of <var>context node</var> is not
    <code>null</code> perform the following steps:

    1.  Let <var>context node</var> be the <a>next sibling</a> of
        <var>context node</var>.
    2.  If <var>context node</var> is not in <var>nodes</var> return
        <var>context node</var> and terminate these steps.

3.  Return <code>null</code>.

To <dfn title="remove an animation node">remove</dfn> a
<var>node</var> from its <a>parent animation group</a> or
<a>player</a>, perform the steps corresponding to the first
matching condition from below, if any:

<div class="switch">

:   If <var>node</var> has a <a>parent animation group</a>,
::  Remove <var>node</var> from the <a>parent animation group</a>'s
    list of <a>child animation nodes</a>.

:   If <var>node</var> is <a>directly associated with
    a player</a>,
::  Disassociate <var>node</var> from the <a>player</a>.

</div>


To <dfn title="insert children">insert</dfn> a series of zero or
more <a>animation nodes</a>, <var>nodes</var>, to
<var>parent</var>'s list of <a>child animation nodes</a> before
<var>reference child</var> perform the following steps for each
<var>node</var> in <var>nodes</var>:</p>

1.  <a title="remove an animation node">Remove</a> <var>node</var>
    from its parent.
2.  Insert <var>node</var> to <var>parent</var>'s list of <a>child
    animation nodes</a> before <var>reference child</var>

<h3 id="the-animationnodelist-interface">The <code>AnimationNodeList</code> interface</h3>

A list of <a>animation nodes</a> may be represented by
an {{AnimationNodeList}}.

The <code>AnimationNodeList</code> interface supports indexed
properties with indices in the range 0 &le; <var>index</var> &lt;
<code>length</code>.

<p class="annotation">
The only reason this interface exists is to provide a familiar
experience for authors familiar with DOM interfaces where child nodes
are accessed via a <code>children</code> member.
</p>

<pre class='idl'>interface AnimationNodeList {
    readonly attribute unsigned long length;
    getter AnimationNode? item (unsigned long index);
};</pre>

<div class="attributes">

:   <dfn attribute for=AnimationNodeList>length</dfn>
::  The number of <a>animation nodes</a> in the list.

</div>

<div class="methods">

:   <dfn method for=AnimationNodeList title="item()">
    getter AnimationNode? item(unsigned long index)</dfn>
::  Returns the <a>animation node</a> at <code>index</code>.
    If <code>index</code> is greater than or equal to
    <code>length</code> returns <code>null</code>.

</div>

<h3 id="the-animationsequence-interface">The <code>AnimationSequence</code> interface</h3>

<a>Animation sequences</a> are represented by the
<code>AnimationSequence</code> interface.

<pre class='idl'>
[Constructor (sequence<AnimationNode>? children,
              optional (unrestricted double or AnimationTimingProperties) timing)]
interface AnimationSequence : AnimationGroup {
    AnimationSequence clone ();
};</pre>

<div class="contructors">

:   <dfn constructor for=AnimationSequence title="AnimationSequence()">
    Constructor (sequence&lt;AnimationNode&gt;? children,
    optional (unrestricted double or AnimationTimingProperties) timing)</dfn>
::  The meaning and handling of each of the parameters in this
    constructor is identical to the <a constructor for="AnimationGroup"
    title="AnimationGroup()">constructor for AnimationGroup</a>.

</div>

<div class="methods">

:   <dfn method for=AnimationSequence title="clone()">
    AnimationSequence clone ()</dfn>
::  Creates a deep copy of this {{AnimationSequence}} object using
    the same procedure as defined for the {{AnimationGroup/clone()}} method of
    the {{AnimationGroup}} interface except that a new {{AnimationSequence}}
    object is created.

</div>

<h3 id="the-animation-interface">The <code>Animation</code> interface</h3>

<a>Animations</a> are represented by the {{Animation}}
interface.

<pre class='idl'>
[Constructor (Animatable? target, object? effect,
              optional (unrestricted double or AnimationTimingProperties) timing)]
interface Animation : AnimationNode {
    attribute (AnimationEffect or EffectCallback)? effect;
    attribute Animatable?                          target;
    Animation clone ();
};</pre>

<div class="contructors">

:   <dfn constructor for=Animation title="Animation()">
:   Constructor ()</dfn>
::  Creates a new {{Animation}} object
    using the following procedure:

    1.  Create a new {{Animation}} object, <var>animation</var>.</li>
    2.  Set <var>timing input</var> as follows,

        <div class="switch">

        :   If <var>timing</var> is an {{AnimationTimingProperties}}
            object,
        ::  Let <var>timing input</var> refer to <var>timing</var>.

        :   If <var>timing</var> is a <code>double</code>,
        ::  Let <var>timing input</var> be a new
            {{AnimationTimingProperties}} object with all members set to
            their default values and <code>duration</code> set to
            <var>timing</var>.

        :   Otherwise (<var>timing</var> is undefined),
        ::  Let <var>timing input</var> be a new
            {{AnimationTimingProperties}} object with all members set to
            their default values.

        </div>

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

    Examples of the usage of this constructor are given in <a
    href="#creating-a-new-animation-object" section></a>.

    Note: as with <a constructor for="AnimationGroup"
    title="AnimationGroup()">the AnimationGroup constructor</a>
    it is possible to pass in an {{AnimationTiming}} object here
    (e.g. the <code>timing</code> member of another
    {{AnimationNode}}) in which case it will be cloned.

    <div class="parameters">

    :   Animatable? target
    ::  The <a>animation target</a> or target pseudo-element.
        This may be <code>null</code> for animations that do not target
        a specific element.

    :   object? effect
    ::  The animation effect used to set the <code>effect</code>
        attribute of the newly-created {{Animation}} object.

        The processing of this parameter is defined normatively in <a
        href="#processing-the-effect-parameter"
        section></a>.
        Following is a non-normative summary of this handing.

        <var>effect</var> 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 <em>not</em> be copied.

        If this parameter is of type {{Keyframe}} or
        <code>sequence&lt;<a dictionary>Keyframe</a>&gt;</code>,
        the <a>animation effect</a> of the newly-created {{Animation}} will be
        a newly-created {{KeyframeEffect}} object
        initialized by using this object as the list of
        <a>keyframes</a> and with all other parameters set to their
        default values.

        If this parameter is <code>null</code>, the newly-created
        {{Animation}} will also have a <code>null</code> animation effect.
    :   optional (unrestricted double or AnimationTimingProperties)
        timing
    ::  The timing properties or <a>iteration duration</a> of the new
        animation.

    </div>

</div>

<div class="attributes">

:   <dfn attribute for=Animation>effect</dfn>
::  The <a>animation effect</a> or <a>custom effect</a> to apply.
    May be <code>null</code> in which case the animation will produce
    no observable effect.

    Issue: 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.

:   <dfn attribute for=Animation>target</dfn>
::  The element or pseudo-element being animated by this object.
    This may be <code>null</code> for animations that do not target
    a specific element such as an animation that produces a sound
    using an audio API.

</div>

<div class="methods">

:   <dfn method for=Animation title="clone()">
    Animation clone ()</dfn>
::  Creates a copy of this {{Animation}} object using the following procedure.

    1.  Let <var>source</var> be the {{Animation}} object to
        clone, that is, this object.</li>
    2.  Let <var>cloned timing</var> be a new
        {{AnimationTimingProperties}} object whose members are assigned
        the value of the attribute with the same name on
        <code><var>source</var>.timing</code>.</li>
    3.  The {{AnimationEffect}} is cloned depending on the type of
        <code><var>source</var>.effect</code> as follows,

        <div class="switch">

        :   If <code><var>source</var>.effect</code> is an
            {{Animation}} object,
        ::  Let <var>cloned effect</var> be the result of calling
            <code><var>source</var>.effect.clone()</code>.
        :   If <code><var>source</var>.effect</code> is an
            {{EffectCallback}} object,
        ::  Let <var>cloned effect</var> be
            <code><var>source</var>.effect</code>.
        :   Otherwise,
        ::  Let <var>cloned effect</var> be <code>null</code>.

        </div>

    4.  Return a new {{Animation}} object created by
        calling the <a constructor for="Animation"
        title="Animation()">Animation constructor</a> with parameters
        <code>Animation(<var>source</var>.target, <var>cloned
        effect</var>, <var>cloned timing</var>)</code>.</li>

</div>

<h4 id="processing-the-effect-parameter">Processing the <var>effect</var> parameter</h4>

The <var>effect</var> parameter, an ECMAScript value passed to the
{{Animation}} constructor or to the
<code>animate</code> operation of the {{Animatable}} interface,
may specify an {{EffectCallback}}, an {{AnimationEffect}},
a <a>Keyframe</a> a sequence of <a>Keyframes</a>, or <span
class="esvalue">null</span>.
However, since callback functions and dictionaries are not
distinguishable in WebIDL, we define the processing of this
parameter for ECMAScript here in prose.

The <dfn>procedure for converting an effect to an IDL value</dfn>
with parameter <var>effect</var> is as follows:

<div class="switch">

:   If <var>effect</var> is <span class="esvalue">null</span>,
::  Return <span class="idlvalue">null</span>.

:   If <var>effect</var> is a <a spec='webidl' status='TR'>platform
    object</a> that implements {{AnimationEffect}},
::  return the IDL value that is a reference to the that platform
    object.

:   If IsCallable(<var>effect</var>) is true,
::  Return the result of applying the <a
    href="http://www.w3.org/TR/WebIDL/#es-callback-function">procedure
    for converting an ECMAScript value to an IDL callback function
    type</a> to <var>effect</var> using {{EffectCallback}} as the
    callback function type.

:   Otherwise,
::  Return a new {{KeyframeEffect}} object constructed passing
    <var>effect</var> as the <var>frames</var> parameter.

</div>

Note: 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.

<h4 id="creating-a-new-animation-object">Creating a new <code>Animation</code> object</h4>

<div class='informative-bg'><em>This section is non-normative</em>

The {{Animation}} constructor offers a number of approaches to
creating a new {{Animation}} object.
At its simplest, an {{Animation}} object that changes the
&lsquo;left&rsquo; property of <var>elem</var> to 100px over three
seconds can be achieved as follows:

<pre class='example sh_javascript'>
var anim = new Animation(elem, { left: '100px' }, 3000);
</pre>

The second parameter, representing the <a>animation effect</a>, may
specify multiple properties, an {{AnimationEffect}} object, or
even a callback function.

<pre class='example sh_javascript'>
// Specify multiple properties at once
var animA = new Animation(elem, { left: '100px', top: '300px' }, 3000);

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

// Share the animation effect of another animation
var animC = new Animation(elem, animB.effect, 3000);

// Supply a custom script-based animation effect
var animD = new Animation(elem, function(time) {
    // (Normally we should check for time===null, but in this case it produces
    //  the correct result anyway)
    document.documentElement.currentScale = 1.0 + time * 2.0;
  }, 3000);
</pre>

The third parameter representing the animation's timing, may
simply be a number representing the <a>iteration duration</a> in
milliseconds as above, or, to specify further timing properties such
as the <a title="animation node playback rate">playback rate</a>,
an {{AnimationTimingProperties}} object can be used as follows:

<pre class='example sh_javascript'>
var anim =
  new Animation(elem, { left: '100px' }, { duration: 3000, playbackRate: 2 });
</pre>

            If the duration is not specified, the <a>intrinsic iteration
            duration</a> is used which, for an <a>animation</a> is zero.
            It is possible to create an animation that simply sets a property
            without any interpolation as follows:

<pre class='example sh_javascript'>
new Animation(elem, { display: 'none' }, { fill: 'forwards' });
</pre>

This is particularly useful in combination with other <a>animations</a> or
<a>animation nodes</a>.
For example, fading an element before switching
&lsquo;display&rsquo; to &lsquo;none&rsquo; can be achieved as
follows,

<pre class='example sh_javascript'>
new AnimationSequence(
  [
    new Animation(elem, { opacity: 0 }, 1000),
    new Animation(elem, { display: 'none' }, { fill: 'forwards' })
  ]
);
</pre>

Having created an {{Animation}}, it can be played using
<code>document.timeline.play(<var>anim</var>)</code>.
For simple effects, however, the <a
href="#extensions-to-the-element-interface"><code>Element.animate</code></a>
shortcut is more convenient since it performs this last step
automatically. For example,

<pre class='example sh_javascript'>
elem.animate({ left: '100px' }, 3000);
</pre>

</div>

<h3 id="the-animatable-interface">The <code>Animatable</code> interface</h3>

Objects that may be the target of an {{Animation}} implement the
{{Animatable}} interface.

<pre class='idl'>
[NoInterfaceObject]
interface Animatable {
    AnimationPlayer                animate (object? effect,
                                            optional (double or AnimationTimingProperties) timing);
    sequence&lt;AnimationPlayer&gt; getAnimationPlayers ();
};
</pre>

<div class="methods">

:   <dfn method for=Animatable title="animate()">
    AnimationPlayer animate(object? effect,
        optional (double or AnimationTimingProperties) timing)</dfn>
::  Creates a new {{Animation}} object
    whose <a>animation target</a> is the object on which the method is
    called, and calls the {{AnimationTimeline/play()}} method of the
    {{AnimationTimeline}} object of the <a>document timeline</a> of the <a
    href="http://www.w3.org/TR/dom/#concept-node-document">node
    document</a> [[!DOM]] of the element passing the newly created
    {{Animation}} as the argument to the method.

    The following code fragment:

    <div><pre class="example sh_javascript">
    var anim = elem.animate({ opacity: 0 }, 2000);
    </pre></div>

    is equivalent to:

    <div><pre class="example sh_javascript">
    var anim = new Animation(elem, { opacity: 0 }, 2000);
    elem.ownerDocument.timeline.play(anim);
    </pre></div>

    Returns the {{AnimationPlayer}} object returned by the
    <code>play</code> method of the {{AnimationTimeline}}.

    <div class="parameters">

    :   object? effect
    ::  The effect to apply.
        This value is passed to the <a
        constructor for="Animation" title="Animation()">Animation
        constructor</a> as the <var>effect</var> parameter and has the
        same interpretation as defined for that constructor.
    :   optional (double or AnimationTimingProperties) timing
    ::  The timing parameters of the animation.
        This value is passed to the <a
        constructor for="Animation" title="Animation()">Animation
        constructor</a> as the <var>timing</var> parameter and has the
        same interpretation as defined for that constructor.

    </div>

:   <dfn method for=Animatable title="getAnimationPlayers()">
    sequence&lt;AnimationPlayer&gt; getAnimationPlayers()</dfn>
::  Returns the set of {{AnimationPlayer}} objects
    whose <a>source content</a> is <a>current</a> or <a>in effect</a> and
    contains at least one <a>animation</a> whose
    <a>animation target</a> is this
    object.

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

    The returned list is sorted in increasing order by <a>player
    sequence number</a>.

    The returned list reflects the state <em>after</em> applying any pending
    changes to animation such as changes to animation-related style properties
    that have yet to be processed.

<h3 id="the-animationeffect-interface">The <code>AnimationEffect</code> interface</h3>

<a>Animation effects</a> are represented by
the <code>AnimationEffect</code> interface.
{{AnimationEffect}} is an abstract interface of which several
concrete subinterfaces are provided.

<pre class='idl'>interface AnimationEffect {
    attribute DOMString                   name;
    attribute IterationCompositeOperation iterationComposite;
    attribute CompositeOperation          composite;
    AnimationEffect clone ();
};</pre>

<div class="attributes">

:   <dfn attribute for=AnimationEffect>name</dfn>
::  A string used to identify the effect.

:   <dfn attribute for=AnimationEffect>iterationComposite</dfn>
::  The <a>iteration composite operation</a> property of this
    <a>animation effect</a> as specified by one of the
    <a>IterationCompositeOperation</a> enumeration values.

:   <dfn attribute for=AnimationEffect>composite</dfn>
::  The <a>composite operation</a> used to composite this
    <a>animation effect</a> with the <a>animation stack</a>, as
    specified by one of the <a>CompositeOperation</a> enumeration
    values.

</div>

<div class="methods">

:   <dfn method for=AnimationEffect title="clone()">
:   AnimationEffect clone ()</dfn>
::  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.

    <p class="todo">
    We either need a more rigorous definition here or (probably
    better) a sets of steps on a per-subclass basis.
    </p>

</div>

<div class="annotation">
In future, we may expose <code>any sample (double?  timeFraction,
double currentIteration, Animatable? target, any
underlyingValue)</code> so that the animation effects can be driven
apart from the timing model.
</div>

<h3 id="the-iterationcompositeoperation-enumeration">The <code>IterationCompositeOperation</code> enumeration</h3>

The possible values of an <a>animation effect</a>'s
<a>iteration composite operation</a> are represented by the
<dfn>IterationCompositeOperation</dfn> enumeration.

<pre class='idl'>
enum IterationCompositeOperation {"replace", "accumulate"};
</pre>

:   <code>replace</code>
::  Corresponds to the <a
    title="iteration composite operation replace">replace</a>
    <a>iteration composite operation</a> value such that the
    <a>intermediate animation value</a> produced is independent of the
    <a>current iteration</a>.
:   <code>accumulate</code>
::  Corresponds to the <a
    title="iteration composite operation accumulate">accumulate</a>
    iteration composite operation value such that
    subsequent iterations of an <a>animation</a> build
    on the final value of the previous iteration.

<h3 id="the-compositeoperation-enumeration">The <code>CompositeOperation</code> enumeration</h3>

The possible values of an <a>animation effect</a>'s
composition behavior are represented by the
<dfn>CompositeOperation</dfn> enumeration.

<pre class='idl'>
enum CompositeOperation {"replace", "add", "accumulate"};
</pre>

:   <code>replace</code>
::  Corresponds to the <a
    title="composite operation replace">replace</a>
    <a>composite operation</a> value such that
    the <a>animation effect</a> overrides the <a>underlying value</a> it
    is combined with.

:   <code>add</code>
::  Corresponds to the <a
    title="composite operation add">add</a>
    <a>composite operation</a> value such that
    the <a>animation effect</a> is <a
    title="animation addition">added</a> to the <a>underlying value</a>
    with which it is combined.

:   <code>accumulate</code>
::  Corresponds to the <a
    title="composite operation accumulate">accumulate</a>
    <a>composite operation</a> value such that
    the <a>animation effect</a> is <a
    title="animation accumulation">accumulated</a> on to the
    <a>underlying value</a>.

<h3 id="the-keyframeeffect-interface">The <code>KeyframeEffect</code> interface</h3>

<a>Keyframe animation effects</a> are represented by the
{{KeyframeEffect}} interface.

<pre class='idl'>
[Constructor (object frames, optional KeyframeEffectOptions options)]
interface KeyframeEffect : AnimationEffect {
    attribute DOMString spacing;
    sequence&lt;ComputedKeyframe&gt; getFrames ();
    void                       setFrames (object frames);
};</pre>

<div class="constructors">

:   <dfn constructor for=KeyframeEffect title="KeyframeEffect()">
:   Constructor ()</dfn>
::  Creates a new {{KeyframeEffect}} object for the
    given set of keyframes.

    <div class="parameters">

    :   object frames
    ::  A {{Keyframe}} object or sequence of {{Keyframe}} objects used for
        calculating animation values for this <a>animation effect</a>.
        The constraints on this parameter and its processing are
        identical to those for <code>setFrames</code>.

    :   optional KeyframeEffectOptions options
    ::  A {{KeyframeEffectOptions}} dictionary defining other aspects
        of the <a>animation effect</a>'s behavior.
        If this parameter is not provided, the default values of the
        dictionary are used.

    </div>

</div>

<div class="attributes">

:   <dfn attribute for=KeyframeEffect>spacing</dfn>
::  The <a title="keyframe spacing mode">spacing mode</a> to use for
    this <a>animation effect</a>.

    Recognized values are defined by the following grammar:

    <blockquote>
      <div class="production">distribute | paced({ident})</div>
    </blockquote>

    <code>{ident}</code> here is an <a
    href="http://www.w3.org/TR/css3-values/#identifier">identifier</a>
    as defined by CSS3 Values [[!CSS3VAL]].

    The meaning of each value is as follows:

    :   distribute
    ::  Use the <a>distribute keyframe spacing mode</a>.
    :   paced({ident})
    ::  Use the <a>paced keyframe spacing mode</a> with the property
        name indicated by <code>{ident}</code> as the <a>paced
        property</a>.

        For example, <code>paced(transform)</code> would indicate that
        the keyframes should be spaced such that changes to the <span
        class="prop-name">transform</span> property occur at
        a constant rate.

    All other values are treated as "distribute" for the purpose of
    animation model calculations.

</div>

<div class="methods">

:   <dfn method for=KeyframeEffect title="getFrames()">
    sequence&lt;ComputedKeyframe&gt; getFrames()</dfn>
::  Returns the <a>keyframes</a> that make up this effect as
    a sequence of {{ComputedKeyframe}} objects.

    The value returned differs from the <var>frames</var> parameter
    passed into <code>setFrames</code> or the constructor for this
    interface in the following ways:

    *   The normalization defined in <a
        href="#normalizing-a-sequence-of-keyframes"
        section></a> is applied to <var>frames</var> which
        may result in some frames being removed or re-ordered and some
        properties being removed.
        This normalization will also cause a single {{Keyframe}}
        object to be replaced with a sequence.
    *   The result of computing the <a>keyframe offset</a>
        of each <a>keyframe</a> as defined in <a
        href="#spacing-keyframes" section></a> is stored in
        the <code>computedOffset</code> member of each frame.

:   <dfn method for=KeyframeEffect title="setFrames()">
    void setFrames(object frames)</dfn>
::  A {{Keyframe}} object or sequence of {{Keyframe}} objects used to
    replace the set of <a>keyframes</a> that make up this effect.

    The processing of the <var>frames</var> parameter is defined in <a
    href="#processing-a-sequence-of-keyframe-objects-or-a-single-item"
    section></a>.
    Subsequently, the resulting sequence of {{Keyframe}} objects is normalized
    using the procedure in <a
    href="#normalizing-a-sequence-of-keyframes"
    section></a> before storing.

</div>

<h4 id="processing-a-sequence-of-keyframe-objects-or-a-single-item">Processing a sequence of <code>Keyframe</code> objects or a single item</h4>

WebIDL does not currently make a dictionary and a sequence
distinguishable but it was felt that allowing both was important
for useability of the <code>animate</code> operation on
{{Animatable}}.
Therefore, we define the processing for handling a parameter
that may be either a single {{Keyframe}} dictionary object, or
a sequence of such objects.

The <dfn>procedure for converting an ECMAScript value into
an IDL keyframe or sequence of keyframes</dfn> with parameter
<var>keyframeOrKeyframeList</var> is as follows:

<div class='switch'>

:   If, using the canonical definition of
    <code>Array.isArray</code> [[!ECMA-262]],
    Array.isArray(<var>keyframeOrKeyframeList</var>) is
    true,
::  Return the result of following the steps for <a
    href="http://www.w3.org/TR/WebIDL/#es-sequence">converting an
    ECMAScript value into an IDL sequence</a> using the <a>procedure
    for converting an ECMAScript value to an IDL Keyframe object</a>
    as the procedure for converting <var>E</var> to an IDL value of
    type <var>T</var>.
:   Otherwise,
::  Return the result of applying the <a>procedure for converting
    an ECMAScript value to an IDL Keyframe object</a> to
    <var>keyframeOrKeyframeList</a>.<dd>

</div>

Issue: Should this be defined in terms of <code>IsIterable</code> instead?


<h4 id="the-keyframeeffectoptions-dictionary">The <code>KeyframeEffectOptions</code> dictionary</h4>

Additional parameters may be passed to the {{KeyframeEffect}}
constructor by providing a {{KeyframeEffectOptions}} object.

<pre class='idl'>dictionary KeyframeEffectOptions {
    DOMString                   name = "";
    IterationCompositeOperation iterationComposite = "replace";
    CompositeOperation          composite = "replace";
    DOMString                   spacing = "distribute";
};</pre>

<div class="attributes">

:   <dfn dict-member for=KeyframeEffectOptions>name</dfn>
::  The value to set for the {{AnimationEffect}}'s {{AnimationEffect/name}}
    property.

:   <dfn dict-member for=KeyframeEffectOptions>iterationComposite</dfn>
::  The <a>iteration composite operation</a> used to define the way
    animation values build from iteration to iteration.

:   <dfn dict-member for=KeyframeEffectOptions>composite</dfn>
::  The <a>composite operation</a> used to composite this
    animation with the <a>animation stack</a>, as specified by one
    of the <a>CompositeOperation</a> enumeration values.
    This is used for all <a>keyframes</a> that do not specify
    a <a>composite operation</a>.

:   <dfn dict-member for=KeyframeEffectOptions>spacing</dfn>
::  The <a title="keyframe spacing mode">spacing mode</a> to apply
    to this <a>animation effect</a>'s <a>keyframes</a>.

    See the {{KeyframeEffect/spacing}} attribute of the
    {{KeyframeEffect}} interface for the recognized values and
    their meaning are described

    Unrecognized values are set on the created {{KeyframeEffect}}
    object, but are treated as "distribute" for the purpose of
    animation model calculations.

</div>


<h4 id="normalizing-a-sequence-of-keyframes">Normalizing a sequence of keyframes</h4>

For each call to <code>setFrames</code> or the {{KeyframeEffect}}
constructor, the following normalization is performed on the passed
in <var>frames</var> parameter before storing its value.

Note: the processing of the ECMAScript value into a suitable IDL
value defined in <a href="#processing-a-keyframe-object"
section></a> is performed before this operation is
initiated.

1.  If <var>frames</var> is a single {{Keyframe}} object, replaces
    <var>frames</var> with
    a new sequence with a single item that is the previous value of
    <var>frames</var>.
2.  If <var>frames</var> is not <a>loosely sorted by offset</a>,
    then,

    <div class='switch'>

    :   If each {{Keyframe}} has a non-null <code>offset</code>,
    ::  Sort <var>frames</var> in ascending order by
        <code>offset</code>.
    :   Otherwise,</dt>
    ::  Throw a DOMException of type
        <code>InvalidModificationError</code>.</dd>

    </div>

3.  If there exist any {{Keyframe}}
    objects in <var>frames</var> whose <code>offset</code> member is
    non-null and less than zero, remove all keyframes
    objects from the start of <var>frames</var> up to and including
    the keyframe with the largest non-null <code>offset</code>
    that is still less than zero.
4.  Likewise, if there exist any {{Keyframe}} objects in
    <var>frames</var> whose <code>offset</code> member is non-null
    and greater than one, remove all <a>keyframes</a> from
    the keyframe with the smallest non-null <code>offset</code>
    that is still greater than one until the end of
    <var>frames</var>.
5.  Remove all property values in <var>frames</var> that are invalid
    or not supported by the implementation.

    Issue: Need to define what invalid means here.

<h3 id="the-keyframe-dictionary">The <code>Keyframe</code> dictionary</h3>

Individual <a>keyframes</a> are represented by a special kind of
{{Keyframe}} dictionary type whose
members map to the properties to be animated.
At the time of writing, this kind of open-ended dictionary cannot
be represented using WebIDL and hence special
ECMAScript-specific handling for this type is defined in
<a href="#processing-a-keyframe-object" section></a>.
No handling is defined for other languages.

<pre class='idl'>
dictionary Keyframe {
    // ... property-value pairs ...
    double?             offset = null;
    DOMString           easing = "linear";
    CompositeOperation? composite = null;
};
</pre>

<div class='attributes'>

:   <dfn dict-member for=Keyframe>offset</dfn>
::  The <a>keyframe offset</a> of the <a>keyframe</a> specified as
    a number between 0.0 and 1.0 inclusive or <code>null</code>.

    <a>Keyframes</a> with offsets outside the range [0.0, 1.0] are
    ignored when calculating animation values as defined in
    <a href="#normalizing-a-sequence-of-keyframes" section></a>.

    A <code>null</code> value indicates that the <a>keyframe</a>
    should be positioned using the <a>keyframe animation effect</a>'s
    <a>keyframe spacing mode</a>.

:   <dfn dict-member for=Keyframe>easing</dfn>
::  The <a>timing function</a> used to transform the progress of time
    from this keyframe until the next keyframe in the series.

    The syntax and error-handling associated with parsing this string
    is identical to that defined for the <code>easing</code> attribute
    of the {{AnimationTiming}} interface.

:   <dfn dict-member for=Keyframe>composite</dfn>
::  The <a>composite operation</a> used to combine the values
    specified in this keyframe with the <a>underlying value</a>.

    If <code>null</code>, the <a>composite operation</a>
    specified on the {{AnimationEffect}} will be used.

</div>


<h4 id="processing-a-keyframe-object">Processing a <code>Keyframe</code> object</h4>

<div class="note">

Since accessing the properties of an ECMAScript user object can
have side effects, the manner in which these properties is
accessed is important.
In light of this consideration the procedure for converting an
ECMAScript object into an IDL {{Keyframe}} object has the following
properties:

*   Each property that is read, is read only once.
*   Properties are read in a well-defined order.
*   Properties corresponding to unsupported target properties or
    attributes are not read.

</div>

The <dfn>procedure for converting an ECMAScript value to an IDL
Keyframe object</dfn> with parameter <var>keyframe input</var>
is as follows:

1.  Let <var>keyframe result</var> be a {{Keyframe}} object with the
    <code>offset</code>, <code>easing</code> and
    <code>composite</code> attributes set to the default dictionary
    values.
2.  Create a list, <var>supported properties</var>, of property
    names and attribute names that can be animated by the
    implementation.
3.  Convert each property name in <var>supported properties</var>
    to the equivalent IDL attribute by applying the <a
    href="http://dev.w3.org/csswg/cssom/#css-property-to-idl-attribute">CSS
    property to IDL attribute</a> algorithm [[!CSSOM]].
4.  If the user agent supports animation of the 'float'
    CSS property, replace "float" in
    <var>supported properties</var> with "cssFloat".
5.  Let <var>animation properties</var> be an empty sequence.
6.  Use the internal \[[Enumerate]] operation on <var>keyframe
    input</var> to iterate over its properties.
    For each <var>property</var> perform the step corresponding to
    the first matching condition from below, if any.

    <div class="switch">

    :   If <var>property</var> is a case-sensitive match for
        the string "offset",</dt>
    ::  Let <var>offset value</var> be the result of calling the \[[Get]]
        internal method on <var>keyframe input</var> with property name
        "offset".
        If <var>offset value</var> is null, set the <code>offset</code>
        member of <var>keyframe result</var> to null.
        Otherwise, set it to the result of applying the <a
        href="http://www.w3.org/TR/WebIDL/#es-double">procedure for
        converting an ECMAScript value into an IDL double</a>
        [[!WEBIDL]] to <var>offset value</a>.

    :   If <var>property</var> is a case-sensitive match for
        the string "easing",</dt>
    ::  Set the <code>easing</code> member of <var>keyframe
        result</var> to the result of applying the <a
        href="http://www.w3.org/TR/WebIDL/#es-DOMString">procedure
        for converting an ECMAScript value to an IDL
        DOMString value</a> [[!WEBIDL]] with the <a
        href="http://www.w3.org/TR/WebIDL/#TreatNullAs">[TreatNullAs=EmptyString]</a>
        annotation in effect, to the result of calling
        the \[[Get]] internal method of <var>keyframe
        input</var> with property name "easing".

        If the resulting string does not conform to the
        grammar defined for the {{AnimationTiming/easing}}
        attribute of the {{AnimationTiming}} interface or
        is not supported by the implementation, then
        set the <code>easing</code> of <var>keyframe result</var>
        to the string &ldquo;linear&rdquo;.

    :   If <var>property</var> is a case-sensitive match for
        the string "composite",</dt>
    ::  Let <var>composite value</var> be the result of calling the \[[Get]]
        internal method on <var>keyframe input</var> with property name
        "composite".
        If <var>composite value</var> is null, set the <code>composite</code>
        member of <var>keyframe result</var> to null.
        Otherwise, set it to the result of applying the <a
        href="http://www.w3.org/TR/WebIDL/#es-enumeration">procedure for
        converting an ECMAScript value to an IDL enumeration type</a>
        [[!WEBIDL]] with <a>CompositeOperation</a> as the enumeration type,
        to <var>composite value</a>.

    :   Otherwise, if <var>property</var> also exists in
        <var>supported properties</var> based on a case-sensitive
        comparison,</dt>
    ::  append <var>property</var> to <var>animation
        properties</var>.</dd>

    </div>

7.  For user agents that support both a prefixed and an
    unprefixed version of some CSS properties, remove all
    prefixed properties from <var>animation properties</var>
    where the corresponding unprefixed version is also
    present in <var>animation properties</var>.

    Note: I'd like to remove this step. Prefixes are history.

8.  Sort <var>animation properties</var> lexicographically by
    the Unicode codepoints that define each element.
9.  Iterate over <var>animation properties</var> from beginning to
    end and for each <var>name</var> in <var>animation
    properties</var> add a new member pair to <var>keyframe
    result</var> as follows:

    *   <em>member name</em>: the result of applying the
        the <a
        href="http://dev.w3.org/csswg/cssom/#idl-attribute-to-css-property">IDL
        attribute to CSS property</a> algorithm [[!CSSOM]] to
        <var>name</var> unless <var>name</var> is
        a case-sensitive match for the string "cssFloat" in
        which case use the string "float".
    *   <em>member value</em>: the result of calling
        <code>ToString</code> on the value returned from the
        \[[Get]] method of <var>keyframe input</var> with property
        name, <var>name</var>.
        If \[[Get]] returns null or undefined, let the member
        value be an empty string.

10. Return <var>keyframe result</var>.

<div class="issue">

The above algorithm gives special meaning to the property names
"offset", "computedOffset", "easing", and "composite".
If a CSS property called "offset" or "composite" is ever
introduced it will clash with the meaning here.

We have a few options:

*   Add special handling at that time to allow addressing the
    property of the same name, e.g. <code>cssOffset</code>.
*   Rename these keywords now to reduce risk of a later clash,
    e.g. "keyframeOffset".

</div>



<h3 id="the-computedkeyframe-dictionary">The <code>ComputedKeyframe</code> dictionary</h3>

<a>Keyframes</a> returned by the {{KeyframeEffect/getFrames()}} method of the
{{KeyframeEffect}} interface are represented using
{{ComputedKeyframe}} dictionary objects.

<pre class='idl'>
dictionary ComputedKeyframe : Keyframe {
    double computedOffset;
};
</pre>

<div class='attributes'>

:   <dfn dict-member for=ComputedKeyframe>computedOffset</dfn>
::  The <a>keyframe offset</a> calculated for this <a>keyframe</a> as
    a result of applying the spacing procedure defined in
    <a href="#spacing-keyframes" section></a>.

</div>

<h3 id="the-effectcallback-callback-function">The <code>EffectCallback</code> callback function</h3>

<a>Custom effects</a> can be defined in script by providing an
{{EffectCallback}} callback function.

<pre class='idl'>
callback EffectCallback = void (double? timeFraction, Animatable currentTarget,
                                Animation animationObject);
</pre>

An {{EffectCallback}} is called each time an {{Animation}}
with which it is
associated is <a title="sampling">sampled</a>.

<div class="parameters">

:   double? timeFraction
::  The <a>time fraction</a> for which to produce an effect.
    When this is <code>null</code>, the function SHOULD
    remove the effect.

:   Animatable currentTarget
::  The <a>animation target</a> on which this callback is expected
    to operate.

    <div class="note">

    Note that <var>currentTarget</var> may differ from
    <code><var>animation</var>.target</code>.

    If the <a>animation target</a> of <var>animation</var>
    is changed between samples, this method will be
    called once with a null <var>timeFraction</var> and the
    previous <a>animation target</a> as the
    <var>currentTarget</var>, then again with the current
    <var>timeFraction</var> and the updated <a>animation
    target</a> as the <var>currentTarget</var>.
    This allows the animation effect to be removed from the old
    <a>animation target</a>.

    </div>

:   Animation animationObject
::  The {{Animation}} object that is being sampled.

<div class="issue">
  This is only named {{animationObject}} because otherwise we end
  up getting a bikeshed error:
  <code>"Multiple possible 'idl' local refs for 'animation'.
    Arbitrarily chose the one with type 'interface' and for ''."</code>
</div>

</div>

<h3 id="extensions-to-the-document-interface">Extensions to the <code>Document</code> interface</h3>

The following extensions are made to the <a title='Document' interface>Document
interface</a> defined in [[!DOM]].

<pre class='idl'>partial interface Document {
    readonly attribute AnimationTimeline timeline;
};</pre>

<div class="attributes">

:   <dfn attribute for=Document>timeline</dfn>
::  The {{AnimationTimeline}} object representing
    the <a>document timeline</a>.

</div>

<h3 id="extensions-to-the-element-interface">Extensions to the <code>Element</code> interface</h3>

Since DOM Elements may be the target of an animation,
the <a class="externalDFN"
href="http://www.w3.org/TR/dom/#interface-element">Element</a>
interface [[!DOM]] is extended as follows:

<pre class="idl">Element implements Animatable</pre>

This allows the following kind of usage.

<pre class="example sh_javascript">
elem.animate({ color: 'red' }, 2000);
</pre>


<h3 id="extensions-to-the-pseudoelement-interface">Extensions to the <code>PseudoElement</code> interface</h3>

Since <a>animations</a> may also target
pseudo-elements, the <a class="externalDFN"
href="http://www.w3.org/TR/cssom/#the-pseudoelement-interface"><code>PseudoElement</code></a>
interface [[!CSSOM]] is also defined to be animatable.

<pre class="idl">PseudoElement implements Animatable</pre>

Issue: This interface is marked at-risk in the <a class="externalDFN"
    href="http://www.w3.org/TR/2013/WD-cssom-20131205/">5 December 2013 WD
    of CSSOM</a>.
    If it is removed, we will need to provide an equivalent definition
    here.

<h3 id="script-execution-and-live-updates-to-the-model">Script execution and live updates to the model</h3>

The interaction between script execution and the state and effects of
the Web Animations model is as follows:

*   Changes made to the Web Animations model via the programming
    interface are reflected immediately in the values returned by the
    interfaces defined in this specification.

    Similarly, methods that operate on the current state of the model
    such as pausing or reversing are applied to a fully-updated timing
    model, that is, after all previous modifications have been
    incorporated.

    <div class="informative-bg"><em>This section is non-normative</em>

    For example, if the {{AnimationPlayer}}
    associated with an {{Animation}} is seeked (see <a section
    href="#setting-the-current-time-of-a-player"></a>) via the programming
    interface, the value returned when querying the
    animation's <code>startTime</code> will reflect updated state of
    the model immediately.

    <div><pre class="example sh_javascript">
      // Initially player.source.computedTiming.localTime is 3000
      player.currentTime += 2000;
      alert(player.source.computedTiming.localTime); // Displays &lsquo;5000&rsquo;
    </pre></div>

    The same concept applies to more complex modifications of the
    Web Animations model such as adding and removing children from
    an {{AnimationGroup}}.

    </div>

*   Querying the computed style of a property affected by
    animation, or the value of an attribute affected by animation,
    returns the value based the <em>current state</em> of the
    model, that is, after incorporating any modifications made using
    the programming interface.

    <div class="informative-bg"><em>This section is non-normative</em>

    For example, if the used style of an element is queried
    immediately after applying a new {{Animation}} to that
    element, the result of the new animation will be
    incorporated in the value returned.

    <div><pre class="example sh_javascript">
    // Set opacity to 0 immediately
    elem.animate({ opacity: 0 }, { fill: 'forwards' });
    alert(window.getComputedStyle(elem).opacity); // Displays &lsquo;0&rsquo;
    </pre></div>

    The means of querying the animated value of an attribute depends
    on the interface defined for the attribute.
    SVG 1.1 [[!SVG11]] defines an additional interface for querying
    animated values.

    <div><pre class="example sh_javascript">
    // Set width to 0 immediately
    rect.animate({ width: '100px' }, { fill: 'forwards' });
    alert(rect.width.animVal.value); // Displays &lsquo;100&rsquo;
    </pre></div>

    </div>

*   Changes made to the model using the programming interface do
    <em>not</em> cause any {{EffectCallback}} functions to be
    called.

    <div class="informative-bg"><em>This section is non-normative</em>

    For example, in the following code, the callback function will
    not be called until <em>after</em> the script block has
    completed during regular sampling.

    <div><pre class="example sh_javascript">
    var timesCalled = 0;
    elem.animate(function() {
      timesCalled++;
    }, 10000);
    alert(timesCalled); // Displays &lsquo;0&rsquo;
    </pre></div>

    </div>


*   Changes to specified style, specified attribute values, and the
    state of the Web Animations model made within the same execution
    block must be synchronized when rendering such that the whole set
    of changes is rendered together.

    <div class="informative-bg"><em>This section is non-normative</em>

    For example, a user agent must not render only the changes to
    specified style made in a script execution block whilst ignoring
    changes to animations.
    This guarantees that the following usage will never produce
    a situation where <em>only</em> the change to specified style is
    rendered without the animation.

    <div><pre class="example sh_javascript">
    // Fade the opacity with fallback for browsers that don't
    // support Element.animate
    elem.style.opacity = '0';
    elem.animate([ { opacity: 1 }, { opacity: 0 } ], 500);
    </pre></div>

    Note that a user agent may render a frame with <em>none</em> of
    the changes made in a script execution block.
    This might happen, for example, if rendering occurs in
    a separate process that is scheduled to run shortly after
    a script execution block completes but before changes made via
    script can be communicated to the process.

    </div>

*   The value returned by the <code>currentTime</code> attribute of
    a <a>document timeline</a> will not change within a script block.

    <div class="informative-bg"><em>This section is non-normative</em>

    For example, querying the <code>currentTime</code> twice within
    a long block of code that is executed in the same script block
    will return the same value as shown in the following example.

    <div><pre class="example sh_javascript">
    var a = document.timeline.currentTime;
    // ... many lines of code ...
    var b = document.timeline.currentTime;
    alert(b - a); // Displays 0
    </pre></div>

    </div>

*   User agents that support Timing control for script-based
    animations [[ANIMATION-TIMING]], prior to <a
    href="http://www.w3.org/TR/animation-timing/#dfn-sample-all-animations"
    class="externalDFN">sampling animation frame request
    callbacks</a> for a given <a
    href="http://www.w3.org/TR/html5/browsers.html#top-level-browsing-context"
    class="externalDFN">top-level browsing context</a>,
    must perform a <a title='single-sample'>sample</a> including 
    executing any eligible
    <a>custom effects</a> (see <a href="#sampling-custom-effects"
    section></a>) for all <a>animation nodes</a>
    <a>associated with a timeline</a> that is the <a>document
    timeline</a> of the
    <a href="http://www.w3.org/TR/html5/browsers.html#active-document"
    class="externalDFN">active document</a> of the <a
    href="http://www.w3.org/TR/html5/browsers.html#top-level-browsing-context"
    class="externalDFN">top-level browsing context</a> or
    of any of its <a
    href="http://www.w3.org/TR/html5/browsers.html#list-of-the-descendant-browsing-contexts"
    class="externalDFN">descendant browsing contexts</a>.
    When performing this <a title='single-sample'>sample</a>, the 
    <a>time value</a> of
    each <a>document timeline</a> must be equal to the <var>time</var>
    passed to animation frame request callbacks for that browsing
    context.

    <div class="informative-bg"><em>This section is non-normative</em>

    As a result of this definition, the time passed to
    a <code>requestAnimationFrame</code> callback acts as
    an alias for <code>document.timeline.currentTime</code>.

    <div><pre class="example sh_javascript">
    window.requestAnimationFrame(function(sampleTime) {
      // Displays &lsquo;0&rsquo;
      alert(sampleTime - document.timeline.currentTime);
    });
    </pre></div>

    </div>


<h2 id="integration-with-media-fragments">Integration with Media Fragments</h2>

The Media Fragments specification [[!MEDIA-FRAGS]] defines a means
for addressing a temporal range of a media resource.
The application of media fragments depends on the MIME type of the
resource on which they are specified.
For resources with the <a class="externalDFN"
href="http://www.w3.org/TR/SVG/intro.html#MIMEType">SVG MIME type</a>
[[!SVG11]], the application of temporal parameters is defined in the <a
href="http://dev.w3.org/fxtf/web-animations/animation-elements.html">
Animation elements</a> specification.

Note: media fragments are defined to operate on resources based on
    their MIME type.
    As a result, temporal addressing may not be supported in all situations
    where Web Animations content is used.

<h2 id="interaction-with-page-display">Interaction with page display</h2>

HTML permits user agents to store <a class="externalDFN"
  href="http://www.w3.org/TR/html51/browsers.html#an-entry-with-persisted-user-state">user-agent
  defined state</a> along with a
<a class="externalDFN"
  href="http://www.w3.org/TR/html51/browsers.html#session-history-entry">session
history entry</a> so that as a user navigates between pages, the
previous state of the page can be restored including state such as
scroll position [[HTML5]].


User agents that pause and resume <a class="externalDFN"
  href="http://www.w3.org/TR/html51/embedded-content-0.html#media-element">media
elements</a> when the referencing document is
unloaded and traversed,
are encouraged to apply consistent handling to documents containing Web
Animations content.
If provided, this behavior SHOULD be achieved by adjusting the <a>time
values</a> of any <a>timelines</a> bound to the <a>global clock</a>.

Issue: Is this at odds with those <a>time values</a> being relative to
    <code>navigationStart</code> and with <code>requestAnimationFrame</code>
    using the same time as <code>document.timeline.currentTime</code>?


<h2 id="implementation-requirements">Implementation requirements</h2>

<h3 id="precision-of-time-values">Precision of time values</h3>

The internal representation of time values is implementation dependant
however, it is RECOMMENDED that user agents be able to represent input
time values with microsecond precision so that 0.000001 is
distinguishable from 0.0.

<h3 id="conformance-criteria">Conformance criteria</h3>

This specification defines an abstract model for animation and, as
such, for user agents that do not support scripting, there are no
conformance criteria since there is no testable surface area.

User agents that do not support scripting, however, may implement
additional technologies defined in terms of this specification in
which case the definitions provided in this specification will form
part of the conformance criteria of the additional technology.

A <dfn>conforming scripted Web Animations user agent</dfn> is a user
agent that implements the <abbr
title="Application Programming Interface">API</abbr> defined in
<a href="#programming-interface" section></a>.

<h2 id="interface-summary">Interface summary</h2>

<div idl-index></div>

<h2 id="acknowledgements">Acknowledgements</h2>

Thank you to Michiel &ldquo;Pomax&rdquo; Kamermans for help with the
equations for a proposed smooth timing function although this feature
has been deferred to a subsequent specification.

Our deep gratitude goes out to <a
href="http://www.southernstarentertainment.com.au/">Southern Star
Animation</a> for their kind generosity and patience in introducing the
editors to the processes and techniques used producing broadcast
animations.

<h2 id="changes-since-last-publication">Changes since last publication</h2>

The following changes have been made since the <a
  href="http://www.w3.org/TR/2013/WD-web-animations-20140605/">5 June
2014 Working Draft</a>:

*   Added definition of <a>unresolved</a> <a>time values</a>.
*   Renamed &ldquo;not started&rdquo; timelines as <a>inactive timelines</a>.
*   Made the association between a <a>player</a> and a <a>timeline</a>
    optional.
*   Removed the concepts of effective timeline time and effective
    current time.
*   Removed the non-normative description of seeking behavior.
*   Added the <a>current finished promise</a> and <a>current ready
    promise</a> objects to <a>players</a>.
*   Modified the procedure to <a>finish a player</a> so that pause
    state is not changed by finishing.
*   Added player <a>play states</a>.
*   Removed player events.
*   Rewrote most of the algorithms for <a>players</a> to accommodate
    asynchronous play/pause/reverse operations.
*   Remove motion path animation effects since this functionality can be
    achieved using the <a href="http://dev.w3.org/fxtf/motion-1/">Motion Path
    Module</a>.
*   Defined that <a>unresolved</a> <a>time values</a> are represented
    by <code>null</code>.
*   Make the <code>getAnimationPlayers</code> method on the
    {{AnimationTimeline}} and {{Animatable}} interfaces return all
    <a>players</a> that are <em>either</em> <a>current</a> <em>or</em> <a>in
    effect</a>.
*   Updated the {{AnimationPlayer}} interface:

    *   Added the <a constructor for="AnimationPlayer">AnimationPlayer()</a>
        constructor.
    *   Made <code>startTime</code> nullable.
    *   Added the <code>playState</code> member and corresponding
        {{AnimationPlayState}} enum.
    *   Added the <code>ready</code> and <code>finished</code> Promise
        attributes.
    *   Removed the <code>paused</code> and <code>finished</code>
        boolean attributes.
    *   Removed the <code>onfinish</code> attribute.

*   Fixed the grammar for <a>&lt;cubic-bezier-timing-function&gt;</a> to
    match CSS Transitions.
*   Introduced the {{ComputedTimingProperties}} dictionary and
    {{AnimationTimingReadOnly}} interface.
*   Moved computed timing from {{AnimationNode}} to a
    {{AnimationNode/computedTiming}} attribute of type
    {{ComputedTimingProperties}}.
*   Removed the <code>player</code> attribute from the {{AnimationNode}}
    interface.
*   Exposed the <a>time fraction</a> to script as
    <code>node.computedTiming.timeFraction</code>.
*   Removed <code>paced</code> as a valid value for {{KeyframeEffect}}'s
    {{KeyframeEffect/spacing}} attribute.
*   Removed the <code>MotionPathEffect</code> interface now that motion path
    animation effects have been removed.
*   Removed the <code>getCurrentAnimations</code> method from the {{Animatable}}
    interface.

Changes since the <a
  href="http://www.w3.org/TR/2013/WD-web-animations-20130625/">25 June
2013 Working Draft</a> are included in <a
  href="http://www.w3.org/TR/2014/WD-web-animations-20140605/#changes-since-last-publication">Appendix
C of the 5 June 2014 Working Draft</a>.

The <a
  href="https://github.com/w3c/web-animations/commits/master">changelog</a>
provides a more detailed history.