Rename policy to 'media-playback-while-not-visible' (#845)

gabrielsanbrito · web-flow · commit 3f3006bdc77b · 2024-07-25T13:08:14.000-07:00
diff --git a/IframeMediaPause/iframe_media_pausing.md b/IframeMediaPause/iframe_media_pausing.md
@@ -1,4 +1,4 @@
-# Pausing iframe media when not rendered
+# Pausing iframe media when not visible
 
 Authors: [Gabriel Brito](https://github.com/gabrielsanbrito), [Steve Becker](https://github.com/SteveBeckerMSFT), [Sunggook Chue](https://github.com/sunggook), Ravikiran Ramachandra
 
@@ -14,7 +14,7 @@ Web applications that host embedded media content via iframes may wish to respon
 
 ## Goals
 
-Propose a mechanism to allow embedder documents to limitedly control embedded iframe media playback based on whether the embedded iframe is [rendered](https://html.spec.whatwg.org/multipage/rendering.html#being-rendered) or not:
+Propose a mechanism to allow embedder documents to limitedly control embedded iframe media playback based on whether the embedded iframe is rendered or not:
 - When the iframe is not rendered, the embedder is able to pause the iframe media playback; and
 -  When the iframe becomes rendered again, the embedder is able to resume the iframe media playback.
 
@@ -25,9 +25,9 @@ It is not a goal of this proposal to allow embedders to arbitrarily control when
 There are scenarios where a website might want to just not render an iframe. For example:
 - A website, in response to an user action, might decide to temporarily not show an iframe that is playing media. However, since it is not possible to mute it, the only option is for the website to remove the iframe completely from the DOM and recreate it from scratch when it should be visible again. Since the embedded iframe can also load many resources, the iframe recreation operation might make the web page slow and spend resources unnecessarily.
 
-## Proposed solution: media-playback-while-not-rendered Permission Policy
+## Proposed solution: media-playback-while-not-visible Permission Policy
 
-We propose creating a new "media-playback-while-not-rendered" [Permission Policy](https://www.w3.org/TR/permissions-policy/) that would pause any media being played by iframes which are not currently [rendered](https://html.spec.whatwg.org/multipage/rendering.html#being-rendered). This would apply whenever the iframe’s `"display"` CSS property is set to `"none"`.
+We propose creating a new "media-playback-while-not-visible" [Permission Policy](https://www.w3.org/TR/permissions-policy/) that would pause any media being played by iframes which are not currently rendered. For example, this would apply whenever the iframe’s `"display"` CSS property is set to `"none"` or when the the `"visibility"` property is set to `"hidden"` or `"collapse"`.
 
 This policy will have a default value of '*', meaning that all of the nested iframes are allowed to play media when not rendered. The example below show how this permission policy could be used to prevent all the nested iframes from playing media. By doing it this way, even other iframes embedded by "foo.media.com" shouldn’t be allowed to play media if not rendered.
 
@@ -39,30 +39,30 @@ This policy will have a default value of '*', meaning that all of the nested ifr
     <title>iframe pausing</title>
   </head>
   <body>
-    <iframe src="https://foo.media.com" allow="media-playback-while-not-rendered 'none'"></iframe>
+    <iframe src="https://foo.media.com" allow="media-playback-while-not-visible 'none'"></iframe>
   </body>
 </html>
 ```
 
-Similarly, the top-level document is also capable of setting this policy on itself by setting the `Permissions-Policy` HTTP header. In the example below, lets' consider a top-level document served by `example.com`. Given the current `Permissions-Policy` HTTP header setup, only iframes that have the same origin as the top-level document (`example.com`) will be able to enable the `media-playback-while-not-rendered` policy.
+Similarly, the top-level document is also capable of setting this policy on itself by setting the `Permissions-Policy` HTTP header. In the example below, lets' consider a top-level document served by `example.com`. Given the current `Permissions-Policy` HTTP header setup, only iframes that have the same origin as the top-level document (`example.com`) will be able to enable the `media-playback-while-not-visible` policy.
 
 `example.com`:
 
 ```HTTP
-Permissions-Policy: media-playback-while-not-rendered=(self)
+Permissions-Policy: media-playback-while-not-visible=(self)
 ```
 
 ```HTML
-<iframe src="https://foo.media.com" allow="media-playback-while-not-rendered 'none'"></iframe>
+<iframe src="https://foo.media.com" allow="media-playback-while-not-visible 'none'"></iframe>
 ```
 
-In this case, `example.com` serves a document that embeds an iframe with a document from `https://foo.media.com`. Since the HTTP header only allows documents from `https://example.com` to inherit `media-playback-while-not-rendered`, the iframe will not be able to use the feature.
+In this case, `example.com` serves a document that embeds an iframe with a document from `https://foo.media.com`. Since the HTTP header only allows documents from `https://example.com` to inherit `media-playback-while-not-visible`, the iframe will not be able to use the feature.
 
 In the past, the ["execution-while-not-rendered" and "execution-while-out-of-viewport"](https://wicg.github.io/page-lifecycle/#feature-policies) permission policies have been proposed as additions to the Page Lifecycle draft specification. However, these policies freeze all iframe JavaScript execution when not rendered, which is not desirable for the featured use case. Moreover, this proposal has not been adopted or standardized.
 
 ## Interoperability with other Web API's
 
-Given that there exists many ways for a website to render audio in the broader web platform, this proposal has points of contact with many API's. To be more specific, there are two scenarios where this interaction might happen. Let's consider an iframe, which is not allowed to play `media-playback-while-not-rendered`:
+Given that there exists many ways for a website to render audio in the broader web platform, this proposal has points of contact with many API's. To be more specific, there are two scenarios where this interaction might happen. Let's consider an iframe, which is not allowed to play `media-playback-while-not-visible`:
 - Scenario 1: When the iframe is not rendered and it attempts to play audio; and
   - Callers should treat this scenario as if they weren't allowed to start media playback. Like when the [`autoplay` permission policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/autoplay) is set to `'none'` for an iframe. 
 - Scenario 2: When the iframe is already playing audio and stops being rendered during media playback. 
@@ -109,13 +109,13 @@ videoElem.addEventListener("pause", (event) => {
 
 ### Web Audio API
 
-The Web Audio API renders audio through an [AudioContext](https://webaudio.github.io/web-audio-api/#AudioContext) object. We propose that the `AudioContext` shouldn't be [allowed to start](https://webaudio.github.io/web-audio-api/#allowed-to-start) whenever it is not rendered and disallowed by the `media-playback-while-not-rendered` policy.
+The Web Audio API renders audio through an [AudioContext](https://webaudio.github.io/web-audio-api/#AudioContext) object. We propose that the `AudioContext` shouldn't be [allowed to start](https://webaudio.github.io/web-audio-api/#allowed-to-start) whenever it is not rendered and disallowed by the `media-playback-while-not-visible` policy.
 
 For scenario 1, if the iframe is not rendered, any `AudioContext` will not be [allowed to start](https://webaudio.github.io/web-audio-api/#allowed-to-start). Therefore, attempting to [create](https://webaudio.github.io/web-audio-api/#dom-audiocontext-audiocontext) a new `AudioContext` or start playback by calling [`resume()`](https://webaudio.github.io/web-audio-api/#dom-audiocontext-resume) shouldn't output any audio and put the `AudioContext` into a [`"suspended"`](https://webaudio.github.io/web-audio-api/#dom-audiocontextstate-suspended) state. It would be recommended for the iframe to wait for a new user interaction event before calling [`resume()`](https://webaudio.github.io/web-audio-api/#dom-audiocontext-resume) - e.g., `click`.
 
 ```js
 // AudioContext being created in a not rendered iframe, where
-// media-playback-while-not-rendered is not allowed. 
+// media-playback-while-not-visible is not allowed. 
 let audioCtx = new AudioContext();
 let oscillator = audioCtx.createOscillator();
 oscillator.connect(audioCtx.destination);
@@ -197,13 +197,13 @@ This proposal does not affect autoplay behavior unless the media-playing iframe
 
 ### Interoperability with `execution-while-not-rendered` and `execution-while-out-of-viewport`
 
-Both `execution-while-not-rendered` and `execution-while-out-of-viewport` permission policies should take precedence over `media-playback-while-not-rendered`. Therefore, in the case that we have an iframe with colliding permissions for the same origin, `media-playback-while-not-rendered` should only be considered if the iframe is allowed to execute. The user agent should perform the following checks:
+Both `execution-while-not-rendered` and `execution-while-out-of-viewport` permission policies should take precedence over `media-playback-while-not-visible`. Therefore, in the case that we have an iframe with colliding permissions for the same origin, `media-playback-while-not-visible` should only be considered if the iframe is allowed to execute. The user agent should perform the following checks:
 
 1. If the origin is not [allowed to use](https://html.spec.whatwg.org/multipage/iframe-embed-object.html#allowed-to-use) the [`"execution-while-not-rendered"`](https://wicg.github.io/page-lifecycle/#execution-while-not-rendered) feature, then:
     1. If the iframe is not [being rendered](https://html.spec.whatwg.org/multipage/rendering.html#being-rendered), freeze execution of the iframe context and return. 
 2. If the origin is not [allowed to use](https://html.spec.whatwg.org/multipage/iframe-embed-object.html#allowed-to-use) the [`"execution-while-out-of-viewport"`](https://wicg.github.io/page-lifecycle/#execution-while-out-of-viewport) feature, then:
     1. If the iframe does not intersect the [viewport](https://www.w3.org/TR/CSS2/visuren.html#viewport), freeze execution of the iframe context and return.
-3. If the origin is not [allowed to use](https://html.spec.whatwg.org/multipage/iframe-embed-object.html#allowed-to-use) the [`"media-playback-while-not-rendered"`](#proposed-solution-media-playback-while-not-rendered-permission-policy) feature, then:
+3. If the origin is not [allowed to use](https://html.spec.whatwg.org/multipage/iframe-embed-object.html#allowed-to-use) the [`"media-playback-while-not-visible"`](#proposed-solution-media-playback-while-not-visible-permission-policy) feature, then:
     1. If the iframe is not [being rendered](https://html.spec.whatwg.org/multipage/rendering.html#being-rendered), pause all media playback from the iframe context and return.
 
 ## Alternative Solutions
