Alternate API design

[chrisn]

In yesterday's Media WG meeting, @jernoble suggested considering an alternate design: Instead of extending document, HTMLMediaElement, and AudioContext, could the API instead have a single method that accepts one of those as parameter and returns the appropriate autoplay policy for that object, so for example:

const policy = navigator.getAutoPlayPolicy(document); // or mediaElement or audioContext

cc @alastor0325 @liberato-at-chromium

[alastor0325]

I like this idea, because (1) it's consistent, and very clear to let developers know where they should ask for the result (no need to switch from different API interfaces) (2) it provides the flexibility of extending this API if we want to expose blocking autoplay to other elements. eg. web speech.

The little drawback is that the output will not be consistent among different inputs. Eg. for web audio, allow-muted doesn't make sense, so navigator.getAutoPlayPolicy(audioContext) would only return allowed or disallowed. I don't know if we have any similar API before, where the returned enum would not fit for every input?

Thank you.

cc @tjenkinson @gkatsev

[alastor0325]

In addition, this proposal can solve my previous quesiton, because it provides the ability to directly check whether audio context can be allowed to play, instead of relying the result of document element.

If we want to follow this way, then we will need to mention that navigator.getAutoPlayPolicy(document) would ONLY indicate the result for media element. Web developers can use that to know if they are allowed to autoplay without the need of creating an actual media element.

[gkatsev]

The little drawback is that the output will not be consistent among different inputs. Eg. for web audio, allow-muted doesn't make sense, so navigator.getAutoPlayPolicy(audioContext) would only return allowed or disallowed.

This may be fine, as WebAudio users will likely only expect allowed or disallowed, where-as media element users may also be expecting allow-muted.

[chrisn]

I agree with @gkatsev. I don't know about precedent with other APIs, but it seems fine to me that we can spec that allow-muted won't apply to AudioContext.

[tjenkinson]

I still prefer this api existing on the object(s) it’s related too. What does having it as a separate api solve? Is it just so that there’s only one function then?

I also don’t think we should allow document as an input because it’s ambiguous. We could spec it today so that document means media element (which still seems a bit confusing), but what happens when there’s a new element in the future that has the concept of autoplay? Would passing in document still satisfy both media element and that new api?

[chrisguttandin]

Hi everyone, I just wanted to mention that 'allow-muted' might make sense for an AudioContext as well at some point in the future.

WebAudio/web-audio-api#2411

[chrisn]

Thanks Christoph, I hadn't seen that!

[alastor0325]

I still prefer this api existing on the object(s) it’s related too. What does having it as a separate api solve? Is it just so that there’s only one function then?

It can help the inconsistent problem between document and webaudio. If we follow this new design, then we will explicitly mention that the result from document would only affect HTMLMediaElement, and for web audio, they should use new designed API to query the result.

Although that can also be done in previous design, that means we would need to add a new API on AudioContext, and if we want to extend the policy to other elements, then we will need to do the same thing for those elements. This will make the spec too scattered because eventually HTML spec editor wants to have all MediaElement's spec merged into the HTML spec, and if we do so, the web audio might also need to be merged into different spec. Rather than doing that, having this consistent interface which allows to query the result by assigning different parameter seems good to me.

I also don’t think we should allow document as an input because it’s ambiguous. We could spec it today so that document means media element (which still seems a bit confusing),

Why having document as an input is ambiguous? If the vague you mean is that the document policy can only answer the question about media elements, this problem still exists no matter we use old API or new API. The policy for different elements in different situation is just not able to be simply answered by one result, so that is why we want to have a new method for web audio itself.

I think the benefit of keeping the document API (or using document as a parameter) is solving the need that was proposed before during the discussion, which is to be able to know the answer without creating any media element.

but what happens when there’s a new element in the future that has the concept of autoplay? Would passing in document still satisfy both media element and that new api?

If we want to extend the policy to other elements, we just need to simply add a different parameter, then it could help to answer the question.

---

Hi everyone, I just wanted to mention that 'allow-muted' might make sense for an AudioContext as well at some point in the future.

Thank for mentioning that! It's good to know!

[tjenkinson]

Thanks. Makes sense to me.

Why having document as an input is ambiguous? If the vague you mean is that the document policy can only answer the question about media elements, this problem still exists no matter we use old API or new API.

Yeh using document in both this new and the previous way feels strange to me, because the answer it’s giving is related more to media element than document. If I had to guess what the api meant without reading the docs passing document I wouldn’t know if it applied to media element or web audio.

I also think you could get the same info that we’re proposing document would return with

navigator.getAutoPlayPolicy(document.createElement(‘video’));

?

so maybe we don’t actually need to handle document?

[chrisguttandin]

What about accepting the HTMLMediaElement prototype as a parameter instead of document?

This would return the general policy for all media elements:

navigator.getAutoPlayPolicy(HTMLMediaElement);

And this would return the policy for a specific media element in the DOM:

navigator.getAutoPlayPolicy(document.querySelector('#my-video'));

Likewise this would return the general policy for any AudioContext:

navigator.getAutoPlayPolicy(AudioContext);

[tjenkinson]

Yeh that looks quite intuitive to me. Accept an instance or the constructor

[gkatsev]

Passing the constructor sounds good to me. I'd just like to avoid having to create a video element to know the default/current autoplay policy should a new video element be created.

Also, can the function be capitalized like getAutoplayPolicy? It'll keep things in line with other methods like requestFullscreen (and the current autoplayPolicy name).

[alastor0325]

Christoph's proposal also sounds good to me, and I also want to avoid simply creating a dummy element to query the general policy for media elements.

As most people seems all agreeing this proposal, if we don't get any disagreement in following few days, then I will create a new PR for that.

can the function be capitalized like getAutoplayPolicy? It'll keep things in line with other methods like requestFullscreen (and the current autoplayPolicy name).

Sounds good to me as well.

Thank y'all so much.

[chrisn]

@liberato-at-chromium @chcunningham do you have any thoughts on this proposal?

[chcunningham]

Deferring to @liberato-at-chromium.

[liberato-at-chromium]

query by constructor or object sgtm. really like it, in fact.

[tidoust]

I said during today's Media WG call that I would look into other occurrences of methods that take a constructor as parameter on the Web platform. I found a few examples which are all about "registering" something:

• The CustomElementRegistry.define() method takes a CustomElementConstructor constructor as parameter.
• The AudioWorkletGlobalScope.registerProcessor() method takes an AudioWorkletProcessorConstructor as parameter.
• The AnimationWorkletGlobalScope.registerAnimator() method takes an AnimatorInstanceConstructor constructor as parameter.
• The LayoutWorkletGlobalScope.registerLayout() method takes a VoidFunction constructor as parameter.
• The PaintWorkletGlobalScope.registerPaint() method takes a VoidFunction constructor as parameter.

There may be more examples. There does not seem to be an easy way to get an exhaustive list automatically given the way such constructs are expressed in Web IDL.

[alastor0325]

Hi, all, sorry for the delay. I just created a new PR for this new API design, and feel free to leave any suggestion there. Thank you.