The final decision of autoplay detection API name

[alastor0325]

Hi, I'm going to help on editing the spec of autoplay detection.

But I found that there are two proposed names for the API on HTMLMediaElement. One is autoplayPolicy from issue#11.

partial interface HTMLMediaElement {
  readonly attribute AutoplayPolicy autoplayPolicy;
};

Another one is the canAutoplay from the explainer, and this one returns a boolean.

partial interface HTMLMediaElement {
  readonly boolean canAutoplay; 
};

Should we decide a final naming and the form for this API before moving things forward? In addition, for the API naming on Document, does everyone agree with using autoplayPolicy like issue#11?

partial interface Document {
  readonly attribute AutoplayPolicy autoplayPolicy;
};

Firefox has implemented an exprimental feature called allowedToPlay based on the previous discussion threads and it's easy for us to change that name to the one that we will decide to use for the final decision.

[alastor0325]

@padenot would you mind to help me loop related people into this discussion? Thank you.

[chrisn]

Welcome @alastor0325, and thank you helping with editing the spec.

If you haven't done so already, please create a W3C account, associate it with your GitHub account, and join the Media WG here.

Looking at the people involved in the early discussion who are still active in the group, I recommend @beaufortfrancois and @jernoble as initial contacts.

[chrisn]

@alastor0325 We discussed briefly on the Media WG call today, @dalecurtis is the person to contact at Google for now.

[dalecurtis]

From the Google side, since we proposed it, we're happy with the existing names. We don't have a strong attachment though, so whatever gains consensus sgtm.

[dalecurtis]

canXXX() methods matches the existing HTMLMediaElement style FWIW.

[alastor0325]

My main concern of returning a boolean on the media element API is that returned information might not be enough for web developers to make the decision.

For instance, when video.canAutoplay() == false, does that mean no autoplay is allowed, or just not allow audible media to autoplay? Then the web developers have to use document.autoplayPolicy together in order to know the exact status for the media element.

if (video.canAutoplay()) {
   video.play();
} else if (!video.canAutoplay() && document.autoplayPolicy == "allowed-muted"){
   video.muted = true;
   video.play();
} else {
   // Not allow to autoplay, do some stuffs here
}

If we provide detailed information on the media element API as well, then we can achieve the same goal by only using one API.

switch (video.autoplayPolicy) {
  case "allowed":
     video.play();
     break;
  case "allowed-muted":
     video.muted = true;
     video.play();
     break;
  default:
     // Not allow to autoplay, do some stuffs here
}

WDYT @dalecurtis?

[dalecurtis]

autoplayPolicy only won't be misleading, but I'm unclear how the API is supposed to interact with user gestures. I.e., the 'do some stuffs here' section :) Are we solving the desired use cases if we only provide the policy value?

[gkatsev]

As a player developer, one of the main things I want is to know whether if I call play, with the current configuration of the media element, it will succeed, without needing to call play. This is what canAutoplay() provides. If it returns true, we can proceed with calling play; if it isn't, we can check the current autoplay policy, adjust the video element properties, and then call play() at that point (or try canAutoplay() again).
For example:

if (video.canAutoplay()) {
  video.play();
} else if (document.autoplayPolicy === 'allowed-muted') {
  video.muted = true;
  video.play();
} else {
 // fall back to click-to-play
}

[dalecurtis]

@gkatsev it sounds like you're expecting that canAutoplay() would include whether or not a user activation is currently present?

[gkatsev]

Yes, it would be a lot less useful to me if it didn't.

[alastor0325]

IMMO I think the user activation is no something we need to discuss in the API level, that is more like an implementation detail. User agents can freely determine what actual mechanism they want to use for blocking autoplay. If they want to use the user acitvation, then the result returned by the autoplay policy detection API should be already considered the user activation and to simply tell web developers whether they can play media or not. User agent can also choose other implementations, such like only allowing autoplay on the media element that has been clicked by users.

In addition, another benefit using video.autoplayPolicy is to allow web developers know the autoplay policy earlier without wating for loading the metadata. Because before loading metadata, we don't know if the media has audio track or not, which means not being able to determine if it's inaudible.

So if the page only allows inaudible media, calling video.canAutoplay before and after loading the metadata could lead to the different result. On Firefox, we regard a video without loading metadata as an audible media because we don't know its status yet.

// Assume that `document.autoplayPolicy === 'allowed-muted'`

// canAutoplay version
let video = document.createElement("video");
video.src = "video_without_audio_track.webm";
await new Promise(r => v.onloadedmetadata = r);
if (video.canAutoplay) {   
  video.play();
} else {
  // handle the case when autoplay is not allowed
  // eg. showing the click-to-play icon
}

// autoplayPolicy version
let video = document.createElement("video");
video.src = "video_without_audio_track.webm";
if (video.autoplayPolicy == "allow-muted") {  
  video.play();
} else {
  // handle the case when autoplay is not allowed
  // eg. showing the click-to-play icon
}

[gkatsev]

IMMO I think the user activation is no something we need to discuss in the API level, that is more like an implementation detail.

Yeah, I would agree with that. As long as if user activation is required, it's included in the decision for the response of canAutoplay.

So if the page only allows inaudible media, calling video.canAutoplay before and after loading the metadata could lead to the different result

That should be fine. canAutoplay should capture the current moment in time. If there isn't enough info, it should err on the side of it can't. Users could wait for loadedmetadata to be sure it won't change.

canAutoplay is simpler, since it tells me directly whether a call to play will succeed or not. video.autoplayPolicy will tell me "you can play muted", now I'll need to check whether my player is muted or there's no audio tracks before proceeding.