Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Define DisplayMediaStreamConstraints.selfBrowserSurface #216

Merged
merged 11 commits into from
Apr 7, 2022
Merged

Define DisplayMediaStreamConstraints.selfBrowserSurface #216

Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e9e8837
x
eladalon1983 Mar 22, 2022
43ebcd2
Update index.html
eladalon1983 Mar 28, 2022
df593d9
Update index.html
eladalon1983 Mar 28, 2022
35dd565
Update index.html
eladalon1983 Mar 28, 2022
11c56f0
Update index.html
eladalon1983 Mar 28, 2022
4ab2a4a
Update index.html
eladalon1983 Mar 28, 2022
e3e74e5
Remove note about tabs
eladalon1983 Apr 5, 2022
c5792d1
Make agreed-upon changes
eladalon1983 Apr 7, 2022
d3ef152
rm default value
eladalon1983 Apr 7, 2022
ae71d76
Clarifying punctuation
eladalon1983 Apr 7, 2022
7aa21ce
Link
eladalon1983 Apr 7, 2022
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
x
  • Loading branch information
@eladalon1983
eladalon1983 committed Mar 22, 2022
commit e9e88371a5d895f285444e993230c34d13fda2bc
67 changes: 67 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -721,6 +721,62 @@ <h2>
</p>
</div>
</section>
<section>
<h2><dfn>CurrentTabPreferenceEnum</dfn></h2>
<p>
Recall that when offering the user a choice of [=display surfaces=]
to capture, the user agent MAY offer the [=browser=] [=display surface=]
in which the application is running. An application might prefer that
this particular [=display surface=] not be offered to the user.
The CurrentTabPreferenceEnum enumeration describes the different
preferences an application might have.
eladalon1983 marked this conversation as resolved.
Show resolved Hide resolved
</p>
<div class="note">
<p>
For clarity's sake, "tab" is used rather than "browser display surface".
</p>
</div>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need this note, since this prose is largely explanatory. I think it's fine to use "tab" here as a shorthand, as long as normative prose below doesn't use it and sticks to defined terms only.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's fine by me. We can remove.
<pre class="idl">
enum CurrentTabPreferenceEnum {
"none",
eladalon1983 marked this conversation as resolved.
Show resolved Hide resolved
"include",
"exclude"
};
</pre>
<table data-dfn-for="CurrentTabPreferenceEnum" class="simple">
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

two spaces
<tbody>
<tr>
<th colspan="2">
Enumeration description
</th>
</tr>
<tr>
<td>
<dfn id="idl-def-CurrentTabPreferenceEnum.none">none</dfn>
</td>
<td>
No preference by the application.
</td>
</tr>
<tr>
<td>
<dfn id="idl-def-CurrentTabPreferenceEnum.include">include</dfn>
</td>
<td>
An application preference of including the current tab.
eladalon1983 marked this conversation as resolved.
Show resolved Hide resolved
</td>
</tr>
<tr>
<td>
<dfn id="idl-def-CurrentTabPreferenceEnum.exclude">exclude</dfn>
</td>
<td>
An application preference of excluding the current tab.
eladalon1983 marked this conversation as resolved.
Show resolved Hide resolved
</td>
</tr>
</tbody>
</table>
</section>
<section>
<h2>DisplayMediaStreamConstraints</h2>
<p>The <dfn>DisplayMediaStreamConstraints</dfn> dictionary is used to
Expand All @@ -732,6 +788,7 @@ <h2>DisplayMediaStreamConstraints</h2>
dictionary DisplayMediaStreamConstraints {
eladalon1983 marked this conversation as resolved.
Show resolved Hide resolved
(boolean or MediaTrackConstraints) video = true;
(boolean or MediaTrackConstraints) audio = false;
CurrentTabPreferenceEnum currentTabPreference = "none";
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could be wrong, but this would be the first time the word "Tab" appears in a web API. I know this was already discussed in the issue, but I can't help thinking we're over-selecting here.

At a conceptual level, the user agent learns whether self-capture (hall of mirrors) is part of the application's use case(s) or not. This seems like valuable information to the user agent, at its most abstract.

It seems less relevant how the user agent ends up acting on this information: whether this applies only to tab-capture or whether it also applies to window capture of the browser window the document is in ... those are really good questions user agents should perhaps be left to figure out, which seems OK to me.

I also don't think it matters if user agents fall short of promises on this today, since this is a hint. E.g. I wouldn't expect browsers to ever exclude full-screen capture over this, but a user agent might take "exclude" as a clue it's OK to blur away the undesirable hall-of-mirrors effect for instance. This way the user agent doesn't need to worry it's stepping on apps that rely on self-capture. cc @youennf

So I'd suggest an iteration on @martinthomson's wording:

Suggested change
CurrentTabPreferenceEnum currentTabPreference = "none";
CurrentTabPreferenceEnum selfCapture = "no-preference";
Copy link
Member Author

@eladalon1983 eladalon1983 Mar 28, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm OK with the s/none/no-preference replacement.
I don't want to accept the s/currentTabPreference/selfCapture suggestion, because this only refers to tabs, and that is intentional - we only got consensus over that in the interim meeting. (Also note how it's CurrentTabPreferenceEnum, btw.)
Copy link
Member

@jan-ivar jan-ivar Mar 29, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(with chair-hat off)

I recall us having rough agreement (not consensus which would require a call on the list) on this being a "hint", which seems to leave this more as an indicator describing application preference, than an explicit control surface to enact certain specific behavior.

Yes I'm bikeshedding, and perhaps suggesting a bit of abstraction here that wasn't discussed before, but I don't read the last meeting as a final word on naming, and would love to hear from others. I think the question of whether to introduce the term "Tab" to the web platform seems orthogonal to discussion over behavior.
Copy link
Member Author

@eladalon1983 eladalon1983 Mar 30, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recall us having rough agreement (not consensus which would require a call on the list) on this being a "hint", which seems to leave this more as an indicator describing application preference, than an explicit control surface to enact certain specific behavior.

This has not changed. We're discussing what the hint will be called.

I think the question of whether to introduce the term "Tab" to the web platform seems orthogonal to discussion over behavior.

If you're not convinced that "tab" can be a convenient shorthand in this case, we can go with the following alternative, although I consider it inferior to "tab":

  SelfCapturePreference selfCaptureBrowser = "no-preference";

  enum SelfCapturePreference {
    "no-preference",
    "include",
    "exclude",
  };

This way:

  1. We use the browser that everyone is already forced to know means "tab" in most relevant contexts.
  2. We have not blocked the way for selfCaptureWindow to be introduced later, if the WG happens to be interested later.

--
But please see my note in the original PR. I think "tab" can be understood well as shorthand for "display surface of type 'browser'". My intention is that this would not formally introduce "tab" into the Web platform, but rather, serve as a localized convenience.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ping @jan-ivar; PTAL.
};</pre>
<section>
<h2>Dictionary <a class="idlType">DisplayMediaStreamConstraints</a>
Expand Down Expand Up @@ -761,6 +818,16 @@ <h2>Dictionary <a class="idlType">DisplayMediaStreamConstraints</a>
the audio track. If <code>false</code>, the {{MediaStream}}
will not contain an audio track.</p>
</dd>
<dt>
<dfn><code>currentTabPreference</code></dfn> of type {{CurrentTabPreferenceEnum}},
defaulting to {{CurrentTabPreferenceEnum/none}}
</dt>
<dd>
Signals application preference for whether the current
[=browser=] [=display surface=] should be included in the list
of [=display surfaces=] offered to the user.
The user agent MAY regard this hint.
eladalon1983 marked this conversation as resolved.
Show resolved Hide resolved
</dd>
</dl>
</section>
</div>
Expand Down