Overview.bs

<style>
	/* crbug.com/1471465 */
	dl.switch > dt {
		counter-increment: list-item 0;
	}
</style>
<pre class='metadata'>
Title: Animation Triggers
Group: CSSWG
Status: ED
Work Status: revising
Shortname: animation-triggers
Level: 1
Group: CSSWG
TR: https://www.w3.org/TR/animation-triggers-1/
ED: https://drafts.csswg.org/animation-triggers-1/
Abstract: Defines CSS properties and an API for creating mechanisms that affect animation
		  playback, based on DOM events resulting from user interaction, or on entry/exit
		  of ranges on animation timelines.
Editor: Robert Flack, Google, flackr@google.com, w3cid 98451
Editor: David Awogbemila, Google, awogbemila@google.com
Editor: Yehonatan Daniv, Wix.com, yehonatand@wix.com, w3cid 136300
Markup Shorthands: markdown yes
</pre>

<pre class=link-defaults>
spec:infra; type:dfn; text:user agent
spec:dom; type:dfn; for:/; text:shadow root
</pre>

<pre class=anchors>
urlPrefix: https://www.w3.org/TR/web-animations-1/; type: dfn
	text: active interval
	text: playback control
</pre>

# Introduction # {#intro}

	This specification defines mechanisms for
	affecting an animation’s playback
	based on various user interactions invoking a specified trigger.
	By specifying a trigger for an animation, that animation
	becomes a <dfn export>triggered animation</dfn>, making its
	playback start delayed until that trigger occurs.
	These triggers can be certain {{Event}}s defined in [[!DOM]],
	or timeline based, such as [=view progress timelines=]. [[!SCROLL-ANIMATIONS-1]]
	
	This module provides both an imperative API building on the
	Web Animations API as well as a declarative API building
	on CSS Animations. [[!CSS-ANIMATIONS-2]] [[!WEB-ANIMATIONS-1]]

## Relationship to other specifications ## {#other-specs}

	Web Animations [[WEB-ANIMATIONS-1]] defines
	an abstract conceptual model for animations on the Web platform,
	with elements of the model including [=animations=] and [=timelines=],
	and associated programming interfaces.
	This specification extends the Web Animations model
	by defining [=triggered animation=]
	and allowing to perform [=playback control=] functions
	on them using triggers.

	This specification introduces both
	programming interfaces for interacting with these concepts,
	as well as CSS properties that apply these concepts
	to CSS Animations [[CSS-ANIMATIONS-2]].
	To the extent the behavior of these CSS properties is described
	in terms of the programming interfaces,
	[=User Agents=] that do not support scripting
	may still conform to this specification
	by implementing the CSS features to behave
	as if the underlying programming interfaces were in place.

	This specification uses the timeline and ranges concept introduced
	in the Scroll-Driven Animations module [[!SCROLL-ANIMATIONS-1]] for
	specifying progress-based timelines and animations.

	Like most operations in CSS besides [=selector=] matching,
	features in this specification operate over
	the [=flattened element tree=].

## Value Definitions ## {#values}

	This specification follows the
	<a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a>
	from [[!CSS2]]
	using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a>
	from [[!CSS-VALUES-3]].
	Value types not defined in this specification
	are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
	Combination with other CSS modules may expand the definitions of these value types.

	In addition to the property-specific values listed in their definitions,
	all properties defined in this specification
	also accept the <a>CSS-wide keywords</a> as their property value.
	For readability they have not been repeated explicitly.

<!-- Big Text: triggers

█████▌ ████▌  ████  ███▌   ███▌  █████▌ ████▌   ███▌
  █▌   █▌  █▌  ▐▌  █▌  █▌ █▌  █▌ █▌     █▌  █▌ █▌  █▌
  █▌   █▌  █▌  ▐▌  █▌     █▌     █▌     █▌  █▌ █▌
  █▌   ████▌   ▐▌  █▌ ██▌ █▌ ██▌ ████   ████▌   ███▌
  █▌   █▌▐█    ▐▌  █▌  █▌ █▌  █▌ █▌     █▌▐█       █▌
  █▌   █▌ ▐█   ▐▌  █▌  █▌ █▌  █▌ █▌     █▌ ▐█  █▌  █▌
  █▌   █▌  █▌ ████  ███▌   ███▌  █████▌ █▌  █▌  ███▌
-->

# Triggers # {#triggers}

	While CSS animations are, by default,
	automatically run as soon as the appropriate 'animation' values have been set on an element,
	the 'animation-trigger' property allows the animation's start to be delayed
	until an appropriate trigger occurs,
	and even paused, restarted, or reset by triggers
	(making it a [=triggered animation=]).

	Currently, two types of <dfn export for=CSS lt="trigger">triggers</dfn> are defined:

	* [=timeline triggers=], managed by the 'timeline-trigger' properties,
		which allow animations to be triggered by entering or leaving certain timeline ranges.
		(Usually, [=view progress timelines=],
		so an animation can be started when an element comes on-screen.)

	* [=event triggers=], managed by the 'event-trigger' properties,
		which allow animations to be triggered by certain user-interaction events,
		such as clicking an element or pressing certain keys.

	A [=trigger=] is <em>defined</em> on some specific triggering element.
	All triggers have a <dfn export for=CSS>trigger name</dfn>,
	and the specific type of trigger dictates how and when it's activated.
	A trigger can define multiple "types" of activation.
	(For example, [=timeline triggers=] can do different things on entry and exit.)

	A [=trigger=] is <em>used</em> on potentially any element,
	creating a <dfn export for=CSS>trigger instance</dfn> on the element.
	(For example, 'animation-trigger' associates a [=trigger instance=]
	with a specific animation on the element.)
	The trigger-using element specifies what actions to take
	when the [=trigger=] activates.

	Note: This design for [=triggers=] and [=trigger instances=],
	and the way they're associated with [=triggered animations=] and <<animation-action>>s,
	is intentionally somewhat generic,
	intended to support using [=triggers=] for <em>other</em> purposes in the future.
	For now, though, [=triggered animations=] are the only user of this feature.

	If a single element attempts to define multiple [=triggers=] of different types
	with the same [=trigger name=],
	it only exposes one of the [=triggers=],
	with [=event triggers=] winning over [=timeline triggers=].

	Note: This order is completely arbitrary
	(based on alphabetic order of the concept name),
	as this is just an error case.

## Trigger Name Scoping: the 'trigger-scope' property ## {#trigger-scope}

	[=Trigger names=] are global by default,
	usable by other elements regardless of their position.
	(Though they are [=tree-scoped names=],
	so have interactions with [=shadow roots=]).
	If multiple elements define [=triggers=] with the same [=trigger name=],
	the [=trigger=] defined by the later element in [=tree order=] is used.

	The 'trigger-scope' property can limit the scope of a name
	to a subtree of the document,
	so elements outside won't see the chosen [=trigger name=],
	and elements inside will only see the version of the [=trigger name=]
	defined inside the scope.

	<pre class=propdef>
	Name: trigger-scope
	Value: none | all | <<dashed-ident>>#
	Initial: none
	Applies to: all elements
	Inherited: no
	Animation type: not animatable
	Computed value: as specified
	</pre>

	This property scopes [=trigger names=] to the subtree of the matching element.
	Its values are:

	<dl dfn-for="trigger-scope" dfn-type=value>
		<dt><dfn>none</dfn>
		<dd>
			No changes in [=trigger name=] scope.

		<dt><dfn>all</dfn>
		<dd>
			Specifies that all [=trigger names=] defined by this element or its descendants--
			whose scope is not already limited by a descendant using 'trigger-scope'--
			to be in scope only for this element's [=flat tree=] descendants;
			and limits descendants to only match [=trigger names=]
			to [=triggers=] within this subtree.

			This value only affects [=trigger names=] in the same tree scope,
			as if it were a [=tree-scoped name/strictly matched=] [=tree-scoped name=].
			(That is, ''trigger-scope: all'' acts identically
			to ''trigger-scope: --foo, --bar, ...'',
			listing all relevant [=trigger names=].)

		<dt><dfn><<dashed-ident>></dfn>
		<dd>
			Specifies that a matching [=trigger name=] defined by this element or its descendants--
			whose scope is not already limited by a descendant using 'trigger-scope'--
			to be in scope only for this element's [=flat tree=] descendants;
			and limits descendants to only match these [=trigger names=]
			to [=triggers=] within this subtree.

			The <<dashed-ident>> represents a [=tree-scoped name/strictly matched=] [=tree-scoped name=],
			i.e. it can only match against [=trigger names=] in the same shadow tree.[[!CSS-SCOPING-1]]
	</dl>

<!-- Big Text: timeline

█████▌ ████ █     █ █████▌ █▌    ████ █    █▌ █████▌
  █▌    ▐▌  ██   ██ █▌     █▌     ▐▌  █▌   █▌ █▌
  █▌    ▐▌  █▌█ █▐█ █▌     █▌     ▐▌  ██▌  █▌ █▌
  █▌    ▐▌  █▌ █ ▐█ ████   █▌     ▐▌  █▌▐█ █▌ ████
  █▌    ▐▌  █▌   ▐█ █▌     █▌     ▐▌  █▌  ██▌ █▌
  █▌    ▐▌  █▌   ▐█ █▌     █▌     ▐▌  █▌   █▌ █▌
  █▌   ████ █▌   ▐█ █████▌ █████ ████ █▌   ▐▌ █████▌
-->

## Timeline Triggers ## {#timeline-triggers}

	A <dfn export>timeline trigger</dfn> is a [=trigger=]
	which is activated when some [=timeline=]
	enters the trigger's <dfn export for="timeline trigger">activation range</dfn>,
	or leaves the trigger's <dfn export for="timeline trigger">active range</dfn>.
	It is defined on an element with the 'timeline-trigger' shorthand property,
	or its longhands.

	A [=timeline trigger=] has a binary <dfn export for="timeline trigger">trigger state</dfn> associated with it;
	it is initially "inactive".
	While it's "inactive",
	the associated [=timeline=] entering (or starting in) the trigger's [=activation range=]
	performs an associated <dfn export for="timeline trigger">entry action</dfn>
	and switches the [=timeline trigger/trigger state=] to "active";
	while it's "active",
	the associated timeline <em>leaving</em> the trigger's [=active range=]
	performs an associated <dfn export for="timeline trigger">exit action</dfn>
	and switches the [=timeline trigger/trigger state=] to "inactive".

	Note: By default, the [=active range=] is the same as the [=activation range=];
	even when manually specified,
	the [=active range=] is always a <em>superset</em> of the [=activation range=].
	The two ranges allow, for example,
	an 'animation-trigger' to start an animation
	when an element is scrolled close to the center of the screen
	(using a [=view progress timeline=] with a relatively small window as the [=activation range=]),
	but not stop it until the element is fully off-screen
	(using <l spec="scroll-animations-1">''animation-timeline-range/cover''</l> as the [=active range=]).

	A [=timeline trigger=] can have one or two actions associated with it
	when used as a trigger on an element
	(such as by 'animation-trigger').
	If two are specified, the first is the trigger's [=timeline trigger/entry action=]
	and the second is the trigger's [=timeline trigger/exit action=];
	if only one is specified, the first is the trigger's [=timeline trigger/entry action=]
	and its [=timeline trigger/exit action=] is to do nothing.

	An element can define multiple [=timeline triggers=],
	using the same [=timeline=] (potentially with different ranges)
	or different ones.
	The set of 'timeline-trigger' longhands
	form a [=coordinating list property group=],
	with 'timeline-trigger-name' as the [=coordinating list base property=],
	and each item in the [=coordinated value list=]
	defining the properties of a single [=timeline trigger=].


### Naming the Trigger: the 'timeline-trigger-name' property ### {#timeline-trigger-name}

	<pre class=propdef>
	Name: timeline-trigger-name
	Value: none | <<dashed-ident>>#
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: N/A
	Computed value: as specified
	Canonical order: per grammar
	Animation type: not animatable
	</pre>

	If ''timeline-trigger-name/none'' is specified,
	the element does not define any [=timeline triggers=].

	If the same <<dashed-ident>> appears multiple times in the list,
	only the last one defines a [=timeline trigger=];
	the preceding ones have no effect.

### Linking a Timeline: the 'timeline-trigger-source' property ### {#timeline-trigger-source}

	<pre class='propdef'>
	Name: timeline-trigger-source
	Value: <<single-animation-timeline>>#
	Initial: auto
	Applies to: all elements
	Inherited: no
	Percentages: N/A
	Computed value: list, each item either
	  the keyword ''single-animation-timeline/none'',
	  the keyword ''single-animation-timeline/auto'',
	  a case-sensitive [=css identifier=],
	  a computed ''scroll()'' function,
	  or
	  a computed ''view()'' function
	Canonical order: per grammar
	Animation type: not animatable
	</pre>

	The 'timeline-trigger-source' property
	specifies the [=timeline trigger's=] associated [=timeline=].
	Values have the same meaning as those of 'animation-timeline',
	except that ''timeline-trigger-source/none''
	instead causes the corresponding entry in the [=coordinated value list=]
	to not define a [=timeline trigger=].

### The Activation Range: the 'timeline-trigger-activation-range' property ### {#timeline-trigger-activation-range-prop}

	<pre class="propdef shorthand">
	Name: timeline-trigger-activation-range
	Value: [ <<'timeline-trigger-activation-range-start'>> <<'timeline-trigger-activation-range-end'>>? ]#
	</pre>

	The 'timeline-trigger-activation-range' property is a [=shorthand property=]
	that sets 'timeline-trigger-activation-range-start' and 'timeline-trigger-activation-range-end'
	together in a single declaration.
	It has the same syntax as the 'animation-range' property.

	The behavior of 'timeline-trigger-activation-range' is defined in [[web-animations-2#trigger-ranges]].

	<pre class="propdef">
	Name: timeline-trigger-activation-range-start, timeline-trigger-activation-range-end
	Value: [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
	Initial: normal
	Applies to: all elements
	Inherited: no
	Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
	Computed value: list, each item either the keyword ''timeline-trigger-activation-range-start/normal'' or a timeline range and progress percentage
	Animation type: not animatable
	</pre>

	The 'timeline-trigger-activation-range-start' and 'timeline-trigger-activation-range-end' properties
	specify the [=timeline trigger=]’s associated [=timeline trigger/activation range=].
	Values have the same meaning as 'animation-range-start' and 'animation-range-end'.

### The Active Range: the 'timeline-trigger-active-range' property ### {#timeline-trigger-active-range-prop}

	<pre class="propdef shorthand">
	Name: timeline-trigger-active-range
	Value: [ <<'timeline-trigger-active-range-start'>> <<'timeline-trigger-active-range-end'>>? ]#
	</pre>

	The 'timeline-trigger-active-range' property is a [=shorthand property=]
	that sets 'timeline-trigger-active-range-start' and 'timeline-trigger-active-range-end'
	together in a single declaration.
	It has the same syntax as the 'animation-range' property.

	The behavior of 'timeline-trigger-active-range' is defined in [[web-animations-2#trigger-ranges]].

	<pre class="propdef">
	Name: timeline-trigger-active-range-start, timeline-trigger-active-range-end
	Value: [ auto | normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]#
	Initial: auto
	Applies to: all elements
	Inherited: no
	Percentages: relative to the specified [=named timeline range=] if one was specified, else to the entire timeline
	Computed value: list, each item either the keyword ''timeline-trigger-active-range-start/normal'' or a timeline range and progress percentage
	Animation type: not animatable
	</pre>

	The 'timeline-trigger-active-range-start' and 'timeline-trigger-active-range-end' properties
	specify the [=timeline trigger=]’s associated [=timeline trigger/active range=].
	Values have the same meaning as 'animation-range-start' and 'animation-range-end',
	with the following addition:

	<dl dfn-type=value dfn-for="timeline-trigger-active-range, timeline-trigger-active-range-start, timeline-trigger-active-range-end">
		: <dfn>auto</dfn>
		::
			The start (for 'timeline-trigger-active-range-start')
			or end (for 'timeline-trigger-active-range-end')
			is equal to the start/end of the [=timeline trigger's=] [=activation range=].
	</dl>

### The 'timeline-trigger' Shorthand ### {#timeline-trigger-shorthand}

	<pre class="propdef shorthand">
	Name: timeline-trigger
	Value: none | [ <<'timeline-trigger-name'>> <<'timeline-trigger-source'>> <<'timeline-trigger-activation-range'>> [ '/' <<'timeline-trigger-active-range'>> ]? ]#
	</pre>

	The 'timeline-trigger' [=shorthand property=]
	sets all of 'timeline-trigger-name',
	'timeline-trigger-source',
	'timeline-trigger-activation-range',
	and optionally 'timeline-trigger-active-range'
	at once.

	A value of <dfn value for=timeline-trigger>none</dfn>
	is equivalent to ''none none normal''.

	Note: Due to significant potential ambiguities in the syntax
	('timeline-trigger-name' vs [=timeline=] names in 'timeline-trigger-source';
	[=activation ranges=] vs [=active ranges=]),
	this shorthand's values must be given in the specified order,
	rather than being settable in any order as is more common.

<!-- Big Text: event

█████▌ █▌   █▌ █████▌ █    █▌ █████▌
█▌     █▌   █▌ █▌     █▌   █▌   █▌
█▌     █▌   █▌ █▌     ██▌  █▌   █▌
████   ▐▌   █  ████   █▌▐█ █▌   █▌
█▌      █  ▐▌  █▌     █▌  ██▌   █▌
█▌      ▐▌ █   █▌     █▌   █▌   █▌
█████▌   ▐█    █████▌ █▌   ▐▌   █▌
-->

## Event Triggers ## {#event-triggers}

	An <dfn export>event trigger</dfn> is a [=trigger=]
	which is activated when certain {{Event}}s are fired at the element.
	It is defined on an element with the 'event-trigger' shorthand property,
	or its longhands.

	An [=event trigger=] can be defined as either stateless or stateful:

	* If stateless, it has a single set of <dfn for="event trigger" lt="enter event">enter events</dfn>
		that activate it.
	* If stateful, it has two sets of events, its [=enter events=]
		and another set of <dfn for="event trigger" lt="exit event">exit events</dfn>.

	[=Event triggers=] are activated when one of its associated {{Event}}s are fired on the page
	with the trigger-defining element as its {{Event/target}}.
	If it's stateful,
	it has a binary <dfn export for="event trigger">trigger state</dfn> associated with it,
	initially "inactive":
	while "inactive", it only activates when the defining element receives one of its [=enter events=],
	performing an associated <dfn export for="event trigger">enter action</dfn>
	and switching its [=event trigger/trigger state=] to "active";
	while "active", it only deactivates when it receives one of its [=exit events=],
	performing an associated <dfn export for="event trigger">exit action</dfn>
	and switching its [=event trigger/trigger state=] back to "inactive".

	A stateless [=event trigger=] must be given exactly one action for its [=trigger instance=].
	A stateful one can be given one or two:
	the first is its [=event trigger/enter action=],
	and the second, if provided, is its [=event trigger/exit action=];
	if the second is not provided,
	the [=event trigger/exit action=] is to do nothing.

	Note: A stateful and stateless [=event trigger=] act differently
	even if you only assign a single action;
	a single-action stateful [=event trigger=] will effectively "turn off"
	until it receives one of its [=exit events=],
	ignoring any of the [=enter events=] after the first,
	while a stateless one will repeatedly trigger for every [=enter event=].

	An element can define multiple [=event triggers=],
	using the same {{Event}}s or different ones.
	The set of 'event-trigger' longhands
	form a [=coordinating list property group=],
	with 'event-trigger-name' as the [=coordinating list base property=],
	and each item in the [=coordinated value list=]
	defining the properties of a single [=event trigger=].

	Issue: The proposal I drew this text from
	specified that it only cares if the element is the *target* of the event.
	We probably want to allow for bubbling and/or capturing,
	possibly as an opt in/out.

### Naming the Trigger: the 'event-trigger-name' property ### {#event-trigger-name}

	<pre class=propdef>
	Name: event-trigger-name
	Value: none | <<dashed-ident>>#
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: N/A
	Computed value: as specified
	Canonical order: per grammar
	Animation type: not animatable
	</pre>

	If ''event-trigger-name/none'' is specified,
	the element does not define any [=event triggers=].

	If the same <<dashed-ident>> appears multiple times in the list,
	only the last one defines an [=event trigger=];
	the preceding ones have no effect.

### Linking an Event: the 'event-trigger-source' property ### {#event-trigger-source}

	<pre class=propdef>
	Name: event-trigger-source
	Value: [ none | <<event-trigger-event>>+ [ / <<event-trigger-event>>+ ]? ]#
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: N/A
	Computed value: as specified
	Animation type: not animatable
	</pre>

	The 'event-trigger-source' property
	specifies what event or events activate the [=event trigger=].
	Its values are:

	<dl dfn-type=value dfn-for=event-trigger-source>
		: <dfn>none</dfn>
		:: The corresponding entry in the [=coordinated value list=] does not define a trigger.

		: <dfn><<event-trigger-event>>+ [ / <<event-trigger-event>>+ ]?</dfn>
		:: Defines what event(s) the [=event trigger=] responds to.

			If a ''/'' is used in the value,
			the [=event trigger=] is stateful;
			the set of events before the ''/'' are the [=event trigger's=] [=enter events=],
			while those after the ''/'' are the [=exit events=].
			(The same events can occur in both sets.)

			Otherwise,
			the [=event trigger=] is stateless,
			and the provided events are its [=enter events=].
	</dl>

	<pre class=prod>
	<dfn><<event-trigger-event>></dfn> = activate | interest | click | touch | dblclick | keypress(<<string>>) | ...
	</pre>

	Issue: Figure out the full set of events we want to handle.

### The 'event-trigger' Shorthand ### {#event-trigger-shorthand}

	<pre class="propdef shorthand">
	Name: event-trigger
	Value: none | [ <<'event-trigger-name'>> <<'event-trigger-source'>> ]#
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: N/A
	Computed value: as specified
	Animation type: not animatable
	</pre>

	The 'event-trigger' [=shorthand property=]
	sets both 'event-trigger-name' and 'event-trigger-source' at once.

	A value of <dfn value for="event-trigger">none</dfn>
	is equivalent to ''none none''.

### The 'animation-trigger' property ### {#animation-trigger-shorthand}

	<pre class=propdef>
	Name: animation-trigger
	Value: [ none | [ <<dashed-ident>> <<animation-action>>+ ]+ ]#
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: N/A
	Computed value: as specified
	Animation type: not animatable
	Canonical order: per grammar
	</pre>

	The 'animation-trigger' property
	specifies whether the animation is a [=triggered animation=],
	and if it is,
	what trigger it responds to
	and what actions it takes in response.
	'animation-trigger' is a [=reset-only sub-property=] of the 'animation' shorthand.
	Its values are:

	<dl dfn-type=value dfn-for=animation-trigger>
		: <dfn>none</dfn>
		::
			The corresponding animation is not a [=triggered animation=].

		: <dfn>[ <<dashed-ident>> <<animation-action>>+ ]+</dfn>
		::
			The corresponding animation is a [=triggered animation=],
			responding to the triggers named by each <<dashed-ident>>,
			and responding by taking the action named by the corresponding <<animation-action>>.
			(See [[#trigger-scope]] for how <<dashed-ident>>s are resolved to [=triggers=].)

			How many <<animation-action>>s a trigger accepts,
			and what exactly activates them,
			is determined by the type of the trigger.
			<span class=note>([=Event triggers=] take one and possibly an optional second, depending on whether they're stateless or stateful;
			[=timeline triggers=] take one and optionally a second.)</span>
			Specifying the wrong number of actions
			(too many or too few)
			is valid syntactically,
			but causes the trigger to have no effect.

			If multiple triggers occur simultaneously,
			they take effect in the order specified.

			If the same <<dashed-ident>> is specified multiple times,
			all but the last have no effect.
	</dl>

	The possible <dfn><<animation-action>></dfn> values,
	and what effect they have in each animation state:

	<table class=data dfn-type=value dfn-for="<animation-action>" link-for-hint="Animation">
		<thead>
			<tr><th>Keyword<th>Extra Effect<th>initial<th>playing<th>paused<th>finished
		</thead>
		<tr><td><dfn>none</dfn><td>—<td>—<td>—<td>—<td>—
		<tr><td><dfn>play</dfn><td>—<td>{{play()}}<td>—<td>{{play()}}<td>{{play()}}
		<tr><td><dfn>play-once</dfn><td>—<td>{{play()}}<td>—<td>{{play()}}<td>—
		<tr><td><dfn>play-forwards</dfn><td>set playback rate to positive<td>{{play()}}<td>—<td>{{play()}}<td>{{play()}}
		<tr><td><dfn>play-backwards</dfn><td>set playback rate to negative<td>{{play()}}<td>—<td>{{play()}}<td>{{play()}}
		<tr><td><dfn>pause</dfn><td>—<td>—<td>{{pause()}}<td>—<td>—
		<tr><td><dfn>reset</dfn><td>set progress to 0<td>—<td>{{pause()}}<td>{{pause()}}<td>{{pause()}}
		<tr><td><dfn>replay</dfn><td>set progress to 0<td>{{play()}}<td>—<td>{{play()}}<td>{{play()}}
		<caption>
			If there is an "effect",
			it happens regardless of the current state,
			before the state-specific action
		</caption>
	</table>

# Privacy Considerations # {#privacy-considerations}

	There are no known privacy impacts of the features in this specification.

# Security Considerations # {#security-considerations}

	There are no known security impacts of the features in this specification.