Skip to content

Commit

Permalink
Add position state to the spec
Browse files Browse the repository at this point in the history
  • Loading branch information
@beccahughes
beccahughes committed Mar 20, 2019
1 parent 3d0f74b commit 2203565
Showing 1 changed file with 144 additions and 0 deletions.
144 changes: 144 additions & 0 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ urlPrefix: https://www.w3.org/TR/appmanifest/; spec: appmanifest
text: image object; url: #dfn-image-object
urlPrefix: https://heycam.github.io/webidl/
type: exception
text: DataError
text: TypeError
urlPrefix: https://tc39.github.io/ecma262/#sec-object.; type: dfn
text: freeze
Expand Down Expand Up @@ -618,6 +619,69 @@ conforming IDL fragments, as described in the Web IDL specification. [[!WEBIDL]]
</ol>
</p>
</section>

<section>
<h3 id='position-state'>Position State</h3>

<p>
A user agent MAY display the <a>current playback position</a> and <a>duration</a>
of a media session in the platform UI depending on platform conventions. The
<dfn>position state</dfn> is the combination of the following:
<ul>
<li>
The <dfn>duration</dfn> of the media.
</li>
<li>
The <dfn>playback rate</dfn> of the media.
</li>
<li>
The <dfn>last reported playback position</dfn> of the media. This is the
playback position of the media when the <a>position state</a> was created.
</li>
</ul>
</p>

<p>
The <a>position state</a> is represented by a {{MediaPositionState}} which MUST
always be stored with the <dfn>last position updated time</dfn>. This is the
time the <a>position state</a> was last updated.
</p>

<p>
The RECOMMENDED way to determine the <a>position state</a> is to monitor the
media elements whose node document's browsing context is the
<a>browsing context</a>.
</p>

<p>
The <dfn>current playback position</dfn> in seconds is computed in the following
way:
<ul>
<li>
The current time in seconds minus the <a>last position updated time</a> in
seconds.
</li>
<li>
Mutliply by the <a>playback rate</a>.
</li>
<li>
Add the <a>last reported playback position</a> in seconds.
</li>
<li>
If this value is less than zero, then return zero.
</li>
<li>
If this value is greater than the <a>duration</a> in seconds, then return the
<a>duration</a> in seconds.
</li>
<li>
Otherwise, return the value.
</li>
</ul>
</p>

</section>

</section>

<h2 id="the-mediasession-interface">The {{MediaSession}} interface</h2>
Expand Down Expand Up @@ -654,6 +718,8 @@ interface MediaSession {
attribute MediaSessionPlaybackState playbackState;

void setActionHandler(MediaSessionAction action, MediaSessionActionHandler? handler);

void setPositionState(MediaPositionState? state);
};
</pre>

Expand Down Expand Up @@ -748,6 +814,29 @@ interface MediaSession {
<var>action</var> and <var>handler</var> on the {{MediaSession}}.
</p>

<p>
The <dfn method for=MediaSession>setPositionState()</dfn> method, when
invoked MUST perform the following steps:

<ul>
<li>
If the <var>state</var> is null then clear the <a>position state</a>.
</li>
<li>
If the <a dict-member for="MediaPositionState">duration</a> is negative,
throw a <a exception>DataError</a>.
</li>
<li>
If the <a dict-member for="MediaPositionState">position</a> is negative
or greater than <a dict-member for="MediaPositionState">duration</a>,
throw a <a exception>DataError</a>.
</li>
<li>
Update the <a>position state</a> and <a>last position updated time</a>.
</li>
</ul>
</p>

<h2 id="the-mediametadata-interface">The {{MediaMetadata}} interface</h2>

<pre class="idl">
Expand Down Expand Up @@ -1016,6 +1105,34 @@ used to specify the {{MediaImage}} object's <a>MIME type</a>. It is a hint as to
the media type of the image. The purpose of this attribute is to allow a user
agent to ignore images of media types it does not support.

<h2 id="the-mediapositionstate-dictionary">The {{MediaPositionState}} dictionary</h2>

<pre class="idl">

dictionary MediaPositionState {
required unrestricted double duration;
double playbackRate = 0.0;
double position = 0.0;
};
</pre>

The {{MediaPositionState}} dictionary is a representation of the current playback
position associated with a {{MediaSession}} that can be used by user agents to
provide a user interface that displays the current playback position and duration.

The <dfn dict-member for="MediaPositionState">duration</dfn> <a>dictionary member</a>
is used to specify the <a>duration</a> in seconds. It should always be positive
and positive infinity can be used to indicate media that is unending.

The <dfn dict-member for="MediaPositionState">playbackRate</dfn> <a>dictionary member</a>
is used to specify the <a>playback rate</a>. It can be positive to represent forward
playback, negative to represent backwards playback or zero to represent media that
is paused.

The <dfn dict-member for="MediaPositionState">position</dfn> <a>dictionary member</a>
is used to specify the <a>last reported playback position</a> in seconds. It should
always be positive.

<h2 id="examples">Examples</h2>

<em>This section is non-normative.</em>
Expand Down Expand Up @@ -1186,6 +1303,33 @@ agent to ignore images of media types it does not support.
</pre>
</div>

<div class="example" id="example-media-position-state">
Setting <a>position state</a>:
<pre class="lang-javascript">
// Media is loaded, set the duration.
navigator.mediaSession.setPositionState({
duration: 60
});

// Media starts playing at the beginning.
navigator.mediaSession.setPositionState({
duration: 60,
playbackRate: 1,
position: 0
});

// Media is paused 30 seconds in.
navigator.mediaSession.setPositionState({
duration: 60,
playbackRate: 0,
position: 30
});

// Media is reset.
navigator.mediaSession.setPositionState(null);
</pre>
</div>

<h2 id="acknowledgments" class="no-num">Acknowledgments</h2>

The editors would like to thank Paul Adenot, Jake Archibald, Tab Atkins,
Expand Down

0 comments on commit 2203565

Please sign in to comment.