Re: [web-animations] API sketch for updated Player behaviour

Hi Brian,

I've put some questions / feedback about your API sketch inline.

On Wed, Oct 16, 2013 at 4:35 PM, Brian Birtles <bbirtles@mozilla.com> wrote:

> Hi again,
>
> Following up the previous post[1] with a sketch of how the API for Option
> C might look:
>
> interface Player {
>              attribute TimedItem? source;
>     readonly attribute Timeline   timeline;
>              attribute double     startTime;
>              attribute double     currentTime;
>     readonly attribute double     timeLag;
>              attribute double     playbackRate;
>     readonly attribute boolean    paused;
>     readonly attribute boolean    ended;
>     void cancel ();
>     void finish ();
>     void play ();
>     void pause ();
>     void reverse ();
> };
>
> Members of interest:
>
> * currentTime - unchanged, you can still set it to anything you like
> (although we'll need to revisit the definition of effective current time
> but that's a separate discussion)
>
> * timeLag - unchanged but incorporates time lag accumulated due to
> "auto-pausing" behaviour outlined in the previous post.[1]
>
> * paused - now readonly and we use play() / pause() to update its state
> much like HTMLMediaElement
>
> * ended - this is taken from HTMLMediaElement. It gets set whenever
> currentTime >= source.endTime (unless I guess playbackRate < 0 and
> currentTime == source.endTime?) This is asymmetrical--it doesn't get set
> when you finish playing in reverse, but that's also how it works in
> HTMLMediaElement.
>

It's a shame this is asymmetric. How important is it to match
HTMLMediaElement's behaviour? I don't think that reverse play is as much of
a consideration for media as it is for animations (but I could be wrong).

If we have to match HTMLMediaElement, maybe we could add another attribute
that is antisymmetric to ended?


> * cancel() - sets source to null. Causes all animation effects produced by
> this player to be cleared.
>

Does this also reset timeLag? What about currentTime and startTime?


> * finish() - jQuery has this and I've sometimes wanted it. Not sure what
> it should do when playbackRate < 0 but for the forwards case, it seeks to
> source.endTime.
>

(a) I'd like it to seek to the edge of the playback range in the current
direction, so that when playing in reverse finish() would seek to the
start. This means that:
finish();
reverse();
will always do full playback of the content in the opposite direction to
last time.

(b) Does finish() seek backwards to source.endTime if the play head is past
endTime already?


> * play() - unpauses if paused is true. In HTML, if you're ended it seeks
> back to the start. I think we should probably do that here for consistency
> even though I don't like these operations that produce very different
> behaviour whether you call them 1ms before or after the player finishes.
>   Not sure what we should do if:
>     - currentTime > source.endTime and playbackRate < 0 -- suggest we seek
> to source.endTime
>     - currentTime < 0 and playbackRate < 0 -- do nothing? or seek to
> source.endTime?
>     - currentTime < 0 and playbackRate > 0 -- suggest we seek to 0
>     - playbackRate = 0 -- do nothing I guess
>   HTML only does restart behaviour when playback is forwards but we might
> want to deviate from that depending on how we define reverse.
>

I agree that seeking back to the start is inelegant, but that it seems like
it's worth matching HTML's behaviour here. I think your suggestions for
edge cases are good - I'd seek to source.endTime in the second case to
remain symmetric.


> * pause() - sets paused to true (and follows all the steps associated with
> that)
>
> * reverse() - sets playbackRate to -playbackRate.
>     If the new playbackRate < 0 and currentTime > source.endTime, seeks to
> source.endTime.
>     If the new playbackRate > 0 and currentTime < 0, seeks to 0.
>
>     Note that the above means that calling reverse() twice is not always a
> no-op, but the cases where it isn't are fairly rare (specifically only when
> we seek outside the content range or shorten the source content after
> ending).
>
> Suggestions are most welcome.
>
> Best regards,
>
> Brian
>
> [1] http://lists.w3.org/Archives/**Public/public-fx/2013OctDec/**0059.html<http://lists.w3.org/Archives/Public/public-fx/2013OctDec/0059.html>
>
>
Sincerely,
    -Shane Stephens