Add the media session and audio session APIs

[foolip]

No description provided.

[ddbeck]

We've used both "API" and "interface" in places like this. What do you think of making some kind of convention? I like the idea of:

• interface to refer to a specific, named method, property, namespace, etc. (e.g., SomeInterface or someMethod(), etc.)
• API to refer to an abstract collection of interfaces (e.g., The WebRTC API).

Suggested change

	description: The `navigator.audioSession` API controls how audio playback interacts with other applications. For example, playing music can pause audio from other applications, while ambient audio can play at the same time.
	description: The `navigator.audioSession` interface controls how audio playback interacts with other applications. For example, playing music can pause audio from other applications, while ambient audio can play at the same time.

[foolip]

Coming from the web standards side, I take "interface" to mean interface in Web IDL and nothing else. So AudioSession is an interface, but navigator.audioSession isn't, that's a property, or attribute in Web IDL lingo.

But yes, we should have some kind of convention. It would be technically correct but not overly helpful to say "the navigator.audioSession object".

Or maybe we just don't use the syntax here, and say "The audio session API"?

[foolip]

Another reason I'm reluctant about "interface" even for Web IDL interface is that it's just an historical accident that we call them interfaces instead of classes. I think we should refer to URL (defined with Web IDL) and Map (defined in ECMAScript) in similar terms. Both are created with new and are a lot like classes, just not called that in specs.

[foolip]

But we should do whatever MDN does...

[ddbeck]

I don't want to wed ourselves too strongly to standards speak (thus JavaScript, not ECMAScript), but I also don't want to put up extra difficulty for standards speakers to contribute here. Since "API" is a bit looser in meaning, how about we only use API and never "interface"?

(If you asked 100 web developers what API stood for, I wonder what % would give the modal answer? 😅)

[ddbeck]

If we want to avoid novelty (and not re-use interface generally), then I suppose my recommendation is to say "The navigator.audioSession object controls…". Longer thoughts on this follow.

---

If we want to match MDN with references to specific things like navigator.something, we've actually got a number of options (because MDN isn't really consistent internally—giving us choices too). Adapted a bit to our constraints, but here we go:

• "The navigator.audioSession property controls…" (puts emphasis on navigator: it's navigator's property)
• "The navigator.audioSession object controls…" (puts emphasis on audioSession: implying the relationship to AudioSession), a highly condensed version of MDN's style of "The audioSession [read-only property of the Navigator interface returns a] AudioSession object"
• "The navigator.audioSession property returns a…" (puts emphasis on the property accessor—I hate this one, it's the worst—MDN shouldn't even be doing this.)

From these, I think option 2 is the "right" one: we care more about the object than we do the fact that navigator gives it to you or the syntax you do it with.

But there's also this "API" route. I think it's harder to do that consistently without doing something novel or without being vague. MDN mostly uses in these Capital Letter API situations, which tends to be in reference to whole specs-as-features. And even then it's not terribly consistent. For example, the Canvas API tutorial starts with text on "how to use the <canvas> element to draw 2D graphics"—which is much closer to our style here anyway.

[ddbeck]

Oh interestingly, the Google style guide explicitly says not to do what I suggested initially:

Don't use API when referring to a method or a class. For example, don't write This resource has one API to mean "This resource has one method."

I'm guessing somebody thought a lot longer and harder about this than I did, so let's definitely not do that.

[foolip]

OK, let's go with "object" for now. It's still a bit novel and maybe "Audio Session API" would be more familiar to some people, but I guess that's an argument for changing the short name as well.

I guess it's time to start another big issue with names that I'm not totally happy with :)

[foolip]

I've filed #822 and don't feel very excited about "object" any longer. @ddbeck do you think it would be acceptable to revert back to "API" while we figure out the guidlines?

[ddbeck]

Yes, there's an issue now, so that's fine with me.

[ddbeck]

Approved, pending the revert of object to API.