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

Update introduction section #204

Merged
merged 10 commits into from
Jul 18, 2024
Merged

Update introduction section #204

Changes from 2 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
7cc7de4
Some minor editorial fixes
chrisn Mar 20, 2023
1898488
Update introduction section
chrisn Nov 24, 2023
92cdbde
Reworded introduction
chrisn Nov 27, 2023
bca8266
Editorial improvements
chrisn Jan 9, 2024
721e72a
Edtiorial improvement
chrisn Jan 9, 2024
785bc80
Update index.bs
chrisn Jul 4, 2024
2b92a89
Update index.bs
chrisn Jul 4, 2024
e97424c
Merge branch 'main' into chrisn-editorial
chrisn Jul 17, 2024
194e9c9
Apply suggestions from code review
chrisn Jul 18, 2024
64f4164
Apply suggestions from code review
chrisn Jul 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 38 additions & 56 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,43 +140,25 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
<em>This section is non-normative</em>

<p>
This specification relies on exposing the following sets of properties:
<ul>
<li>
<p>
An API to query the user agent with regards to the decoding and
encoding abilities of the device based on information such as the
codecs, profile, resolution, bitrates, etc. The API exposes
information such as whether the playback should be smooth and power
efficient.
</p>
<p>
The intent of purposes of the decoding capabilities API is to provide
a powerful replacement to API such as
{{MediaSource/isTypeSupported()}} or
{{HTMLMediaElement/canPlayType()}} which are vague and mostly help the
callers to know if something can not be decoded but not how well it
should perform.
</p>
</li>
<li>
<p>
Better information about the display properties such as supported
color gamut or dynamic range abilities in order to pick the right
content for the display and avoid providing HDR content to an SDR
display.
</p>
</li>
<li>
<p>
Real time feedback about the playback so an adaptative streaming can
alter the quality of the content based on actual user perceived
quality. Such information will allow websites to react to a pick of
CPU/GPU usage in real time. It is expected that this will be tackled
as part of the [[media-playback-quality]] specification.
</p>
</li>
</ul>
This specification defines an API to query the user agent with regards
to the audio and video decoding and encoding abilities of the device,
chrisn marked this conversation as resolved.
Show resolved Hide resolved
based on information such as the codecs, profile, resolution, bitrates,
etc., of the media. The API exposes information such as whether the
chrisn marked this conversation as resolved.
Show resolved Hide resolved
playback should be smooth and power efficient.
</p>
<p>
The intent of the decoding capabilities API is to provide a powerful
chrisn marked this conversation as resolved.
Show resolved Hide resolved
replacement for APIs such as {{MediaSource/isTypeSupported()}} or
{{HTMLMediaElement/canPlayType()}} which are vague and mostly help
chrisn marked this conversation as resolved.
Show resolved Hide resolved
callers know if something cannot be decoded but not how well it
should perform.
chrisn marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
This specification focuses on encoding and decoding capabilities.
It is expected to be used with other web APIs that provide information about
the display properties, such as supported color gamut or dynamic range abilities,
chrisn marked this conversation as resolved.
Show resolved Hide resolved
to enable web applications to pick the right content for the display and to,
chrisn marked this conversation as resolved.
Show resolved Hide resolved
for example, avoid providing HDR content to an SDR display.
</p>
</section>

Expand Down Expand Up @@ -211,7 +193,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/

<p>
The input to the decoding capabilities is represented by a
{{MediaDecodingConfiguration}} dictionary and the input of the encoding
{{MediaDecodingConfiguration}} dictionary and the input to the encoding
capabilities by a {{MediaEncodingConfiguration}} dictionary.
</p>
<p>
Expand Down Expand Up @@ -278,7 +260,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
A {{MediaDecodingConfiguration}} has three types:
<ul>
<li><dfn for='MediaDecodingType' enum-value>file</dfn> is used to
represent a configuration that is meant to be used for a plain file
represent a configuration that is meant to be used for plain file
playback.</li>
<li><dfn for='MediaDecodingType' enum-value>media-source</dfn> is used
to represent a configuration that is meant to be used for playback of
Expand Down Expand Up @@ -306,7 +288,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
<ul>
<li><dfn for='MediaEncodingType' enum-value>record</dfn> is used to
represent a configuration for recording of media,
<span class="informative">e.g. using {{MediaRecorder}} as defined in
<span class="informative">e.g., using {{MediaRecorder}} as defined in
[[mediastream-recording]]</span>.</li>
<li><dfn for='MediaEncodingType' enum-value>webrtc</dfn> is used to
represent a configuration that is meant to be transmitted using
Expand Down Expand Up @@ -667,14 +649,14 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/

<p>
The <dfn for='AudioConfiguration' dict-member>bitrate</dfn> member
represents the number of average bitrate of the audio track. The bitrate
represents the average bitrate of the audio track. The bitrate
is the number of bits used to encode a second of the audio track.
</p>

<p>
The <dfn for='AudioConfiguration' dict-member>samplerate</dfn>
represents the samplerate of the audio track in. The samplerate is the
number of samples of audio carried per second. samplerate is only
member represents the samplerate of the audio track in. The samplerate
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
member represents the samplerate of the audio track in. The samplerate
member represents the sample rate of the audio track in. The sample rate

Copy link
Member Author

Choose a reason for hiding this comment

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

We also need to remove "in" here. I'll fix this.

chrisn marked this conversation as resolved.
Show resolved Hide resolved
is the number of samples of audio carried per second. samplerate is only
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
is the number of samples of audio carried per second. samplerate is only
is the number of samples of audio carried per second. sample rate is 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.

samplerate here refers to the dictionary member, so i think shouldn't change.

applicable to the decoding types {{media-source}}, {{file}}, and
{{MediaDecodingType/webrtc}} and the encoding type
{{MediaEncodingType/webrtc}}.
Expand Down Expand Up @@ -821,11 +803,11 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/

<p class='note'>
Authors can use {{MediaCapabilitiesInfo/powerEfficient}} in concordance
with the Battery Status API [[battery-status]] in order to determine
with the Battery Status API [[battery-status]] to determine
whether the media they would like to play is appropriate for the user
configuration. It is worth noting that even when a device is not power
constrained, high power usage has side effects such as increasing the
temperature or the fans noise.
temperature or fan noise.
</p>

<p>
Expand Down Expand Up @@ -1002,7 +984,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
context's <a>Document</a>.
</li>
<li>
Let <var>implementation</var> be the implementation of <code>config.keySystemConfiguration.keySystem</code>
Let <var>implementation</var> be the implementation of <code>config.keySystemConfiguration.keySystem</code>.
</li>

<li>
Expand Down Expand Up @@ -1042,11 +1024,11 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
<ol>
<li>
Set the {{EME/robustness}} attribute to <code>
config.keySystemConfiguration.audio.robustness</code>
config.keySystemConfiguration.audio.robustness</code>.
</li>
<li>
Set the {{EME/encryptionScheme}} attribute to <code>
config.keySystemConfiguration.audio.encryptionScheme</code>
config.keySystemConfiguration.audio.encryptionScheme</code>.
</li>
</ol>
</li>
Expand All @@ -1070,7 +1052,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
</li>
<li>
Set the {{EME/encryptionScheme}} attribute to <code>
config.keySystemConfiguration.video.encryptionScheme</code>
config.keySystemConfiguration.video.encryptionScheme</code>.
</li>
</ol>
</li>
Expand Down Expand Up @@ -1106,7 +1088,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
</li>
</ol>
</li>
<li>Return <var>access</var></li>
<li>Return <var>access</var>.</li>
</ol>
</p>
</section>
Expand Down Expand Up @@ -1220,7 +1202,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
<section>
<p>
This specification does not introduce any security-sensitive information
or APIs but is provides an easier access to some information that can be
or APIs but it provides easier access to some information that can be
used to fingerprint users.
</p>

Expand All @@ -1234,7 +1216,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
already be discovered via experimentation with the exception that the
API will likely provide more accurate and consistent information. This
information is expected to have a high correlation with other
information already available to the web pages as a given class of
information already available to web pages as a given class of
device is expected to have very similar decoding/encoding capabilities.
In other words, high end devices from a certain year are expected to
decode some type of videos while older devices may not. Therefore, it is
Expand All @@ -1243,8 +1225,8 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
</p>

<p>
HDR detection is more nuanced. Adding colorGamut, transferFunction, and
hdrMetadataType has the potential to add significant entropy. However,
HDR detection is more nuanced. Adding {{colorGamut}}, {{transferFunction}}, and
{{hdrMetadataType}} has the potential to add significant entropy. However,
for UAs whose decoders are implemented in software and therefore whose
capabilities are fixed across devices, this feature adds no effective
entropy. Additionally, for many cases, devices tend to fall into large
Expand All @@ -1255,7 +1237,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
<p>
If an implementation wishes to implement a fingerprint-proof version of
this specification, it would be recommended to fake a given set of
capabilities (ie. decode up to 1080p VP9, etc.) instead of returning
capabilities (i.e., decode up to 1080p VP9, etc.) instead of returning
always yes or always no as the latter approach could considerably
degrade the user's experience. Another mitigation could be to limit
these Web APIs to top-level browsing contexts. Yet another is to use a
Expand Down Expand Up @@ -1415,7 +1397,7 @@ spec: secure-contexts; urlPrefix: https://www.w3.org/TR/secure-contexts/
</div>

<div class="note">
The following example can also be found in e.g.
The following example can also be found in
<a href="https://codepen.io/miguelao/pen/bWNwej/left?editors=0010#0">
this codepen</a> with minimal modifications.
</div>
Expand Down
Loading