Skip to content

Commit 116612c

Browse files
hochhoch
authored
AudioContext.onerror (#2580)
* initial commit * fixing XML errors * adding section 2.5 * fixed markup for better alignment * add notes for fallback behavior * fix typo * fix duplicate id * fix amendment button bug * handling 2 cases * clean up * fire two events * addressing comments * addressing comments * addressing more comments * add ErrorEvent and minor fixes * more ErrorEvent fix * added step for policy check
1 parent 22d71ec commit 116612c

File tree

1 file changed

+151
-41
lines changed

1 file changed

+151
-41
lines changed

‎index.bs

Lines changed: 151 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,7 @@ window.addEventListener('load', (event) => {
182182
ListAmendments("c2400", "Proposed Addition", "change-list-2400");
183183
ListAmendments("c2512", "Proposed Addition", "change-list-2512");
184184
ListAmendments("c2450", "Proposed Addition", "change-list-2450");
185+
ListAmendments("c2567", "Proposed Addition", "change-list-2567");
185186
});
186187
</script>
187188
<style>
@@ -1718,9 +1719,11 @@ enum AudioSinkType {
17181719
<a href="https://github.com/WebAudio/web-audio-api/issues/2444">Issue 2444
17191720
</a> Add AudioRenderCapacity Interface <br>
17201721
<a href="https://github.com/WebAudio/web-audio-api/issues/2400" id="c2400-2">
1721-
Issue 2400</a> Access to a different output device
1722+
Issue 2400</a> Access to a different output device <br>
1723+
<a href="https://github.com/WebAudio/web-audio-api/issues/2567" id="c2567-1">
1724+
Issue 2567</a>. Device-related error reporting via AudioContext
17221725
<div class="amendment-buttons"></div>
1723-
<del cite="#c2444 #c2400">
1726+
<del cite="#c2444 #c2400 #c2567">
17241727
<xmp class="idl extract" data-no-idl>
17251728
[Exposed=Window]
17261729
interface AudioContext : BaseAudioContext {
@@ -1739,7 +1742,7 @@ enum AudioSinkType {
17391742
};
17401743
</xmp>
17411744
</del>
1742-
<ins cite="#c2444 #2400">
1745+
<ins cite="#c2444 #2400 #2567">
17431746
<xmp class="idl">
17441747
[Exposed=Window]
17451748
interface AudioContext : BaseAudioContext {
@@ -1749,6 +1752,7 @@ enum AudioSinkType {
17491752
[SecureContext] readonly attribute (DOMString or AudioSinkInfo) sinkId;
17501753
[SecureContext] readonly attribute AudioRenderCapacity renderCapacity;
17511754
attribute EventHandler onsinkchange;
1755+
attribute EventHandler onerror;
17521756
AudioTimestamp getOutputTimestamp ();
17531757
Promise<undefined> resume ();
17541758
Promise<undefined> suspend ();
@@ -1968,53 +1972,90 @@ Constructors</h4>
19681972
Sending a <a>control message</a> to start processing means
19691973
executing the following steps:
19701974

1971-
<div class="addition proposed" id="c2400-5">
1972-
<span class="marker">Proposed Addition</span><br>
1973-
<a href="https://github.com/WebAudio/web-audio-api/issues/2400">Issue
1974-
2400</a> Access to a different output device
1975-
<div class="amendment-buttons"></div>
1976-
<del cite=#2400>
1977-
1. Attempt to <a href="#acquiring">acquire system resources</a>.
1978-
In case of failure, abort the following steps.
1979-
1980-
3. Set the {{[[rendering thread state]]}} to <code>running</code> on the {{AudioContext}}.
1975+
<div class="addition proposed">
1976+
<div class="addition proposed" id="c2400-5" style="border:0; margin:0; padding:0">
1977+
<span class="marker">Proposed Addition
1978+
<a href="https://github.com/WebAudio/web-audio-api/issues/2400">Issue 2400</a>.
1979+
</span>
1980+
Access to a different output device
1981+
<div class="amendment-buttons"></div>
1982+
</div>
1983+
<div class="addition proposed" id="c2567-2" style="border:0; margin:0; padding:0">
1984+
<span class="marker">Proposed Addition
1985+
<a href="https://github.com/WebAudio/web-audio-api/issues/2567">Issue 2567</a>.
1986+
</span>
1987+
Device-related error reporting via AudioContext
1988+
<div class="amendment-buttons"></div>
1989+
</div>
19811990

1982-
1. <a href="https://html.spec.whatwg.org/multipage/media.html#queue-a-media-element-task">
1983-
queue a media element task</a> to execute the following steps:
1991+
<del cite="#2400 #2567">
1992+
1. Attempt to <a href="#acquiring">acquire system resources</a>.
1993+
In case of failure, abort the following steps.
19841994

1985-
1. Set the {{BaseAudioContext/state}} attribute of the {{AudioContext}} to "{{AudioContextState/running}}".
1995+
1. Set the {{[[rendering thread state]]}} to <code>running</code> on the {{AudioContext}}.
19861996

19871997
1. <a href="https://html.spec.whatwg.org/multipage/media.html#queue-a-media-element-task">
1988-
queue a media element task</a> to <a spec="dom" lt="fire an event">fire an event
1989-
</a> named {{BaseAudioContext/statechange}} at the {{AudioContext}}.
1990-
</del>
1991-
<ins cite=#2400>
1992-
1. Attempt to <a href="#acquiring">acquire system resources</a> to use a
1993-
following audio output device based on {{AudioContext/[[sink ID]]}} for
1994-
rendering:
1998+
queue a media element task</a> to execute the following steps:
19951999

1996-
* The default audio output device for the empty string.
1997-
* A audio output device identified by {{AudioContext/[[sink ID]]}}.
1998-
1999-
In case of failure, abort the following steps.
2000+
1. Set the {{BaseAudioContext/state}} attribute of the {{AudioContext}} to "{{AudioContextState/running}}".
20002001

2001-
1. Set the {{[[rendering thread state]]}} to <code>running</code> on the
2002-
{{AudioContext}}.
2002+
1. [=Queue a media element task=] to [=fire an event=] named
2003+
{{BaseAudioContext/statechange}} at the {{AudioContext}}.
20032004

2004-
1. <a href="https://html.spec.whatwg.org/multipage/media.html#queue-a-media-element-task">
2005-
Queue a media element task</a> to execute the following steps:
2005+
</del>
2006+
<ins cite="#2400 #2567">
2007+
1. Let |document| be the [=current settings object=]'s [=relevant global object=]'s
2008+
[=associated Document=].
20062009

2007-
1. Set the {{BaseAudioContext/state}} attribute of the {{AudioContext}}
2008-
to "{{AudioContextState/running}}".
2010+
1. Attempt to [=acquire system resources=] to use a following audio output device
2011+
based on {{AudioContext/[[sink ID]]}} for rendering:
20092012

2010-
1. <a spec="dom" lt="fire an event">Fire an event</a> named
2011-
{{BaseAudioContext/statechange}} at the {{AudioContext}}.
2012-
</ins>
2013+
* The default audio output device for the empty string.
2014+
* A audio output device identified by {{AudioContext/[[sink ID]]}}.
2015+
2016+
1. If resource acquisition fails, execute the following steps:
2017+
2018+
1. If |document| is not allowed to use the feature identified by
2019+
<code>"speaker-selection"</code>, abort these substeps.
2020+
2021+
1. [=queue a media element task=] to [=fire an event=] using {{ErrorEvent}}
2022+
at the {{AudioContext/error}} of the {{AudioContext}}, and abort the
2023+
following steps.
2024+
2025+
1. Set [=this=] {{[[rendering thread state]]}} to <code>running</code> on the
2026+
{{AudioContext}}.
2027+
2028+
1. [=Queue a media element task=] to execute the following steps:
2029+
2030+
1. Set the {{BaseAudioContext/state}} attribute of the {{AudioContext}}
2031+
to "{{AudioContextState/running}}".
2032+
2033+
1. [=fire an event=] named {{BaseAudioContext/statechange}} at the
2034+
{{AudioContext}}.
2035+
</ins>
2036+
2037+
</div>
20132038
</div>
2039+
2040+
<div class="proposed addition" id="c2567-3">
2041+
<span class="marker">Proposed Addition
2042+
<a href="https://github.com/WebAudio/web-audio-api/issues/2567">Issue 2567</a>.
2043+
</span>
2044+
Device-related error reporting via AudioContext
2045+
<div class="amendment-buttons"></div>
2046+
<del>
20142047
Note: It is unfortunately not possible to programatically notify authors
20152048
that the creation of the {{AudioContext}} failed. User-Agents are
20162049
encouraged to log an informative message if they have access to a logging
20172050
mechanism, such as a developer tools console.
2051+
</del>
2052+
<ins>
2053+
NOTE: In cases where an {{AudioContext}} is constructed with no arguments and resource
2054+
acquisition fails, the User-Agent will attempt to silently render the audio graph using
2055+
a mechanism that emulates an audio output device.
2056+
</ins>
2057+
</div>
2058+
20182059
</div>
20192060

20202061
<div class="addition proposed" id="c2456-2">
@@ -2111,10 +2152,8 @@ Attributes</h4>
21112152
2444</a>.
21122153
</span>
21132154
Add AudioRenderCapacity Interface
2114-
<div class="amendment-buttons">
2115-
Buttons here
2116-
</div>
2117-
<ins cite=#c2444>
2155+
<div class="amendment-buttons"></div>
2156+
<ins cite=#c2444>
21182157
: <dfn>renderCapacity</dfn>
21192158
::
21202159
Returns an {{AudioRenderCapacity}} instance associated with
@@ -2146,7 +2185,30 @@ Attributes</h4>
21462185
is available to check the readiness of the initial output device.
21472186

21482187
</ins>
2149-
</dl>
2188+
</div>
2189+
2190+
<div class="proposed addition" id="c2567-4">
2191+
<span class="marker">Proposed Addition
2192+
<a href="https://github.com/WebAudio/web-audio-api/issues/2567">Issue 2567</a>.
2193+
</span>
2194+
Device-related error reporting via AudioContext
2195+
<div class="amendment-buttons"></div>
2196+
<ins cite=#2567>
2197+
: <dfn>onerror</dfn>
2198+
::
2199+
An [=event handler=] for the {{ErrorEvent}} dispatched from an {{AudioContext}}. The event
2200+
type of this handler is <dfn event for=AudioContext>error</dfn> and the user agent can
2201+
dispatch this event in the following cases:
2202+
2203+
* When initializing and activating a selected audio device encounters failures.
2204+
* When the audio output device associated with an {{AudioContext}} is disconnected while
2205+
the context is {{AudioContextState/running}}.
2206+
* When the operating system reports an audio device malfunction.
2207+
2208+
</ins>
2209+
</div>
2210+
2211+
</dl>
21502212

21512213
<h4 id="AudioContext-methods">
21522214
Methods</h4>
@@ -12864,6 +12926,54 @@ running the algorithm for an {{AudioNode}}, using an <a>input
1286412926
buffer</a> and the value(s) of the {{AudioParam}}(s) of this
1286512927
{{AudioNode}} as the input for this algorithm.
1286612928

12929+
12930+
<div class="addition proposed" id="c2567-5">
12931+
<span class="marker">Proposed addition
12932+
<a href="https://github.com/WebAudio/web-audio-api/issues/2567">Issue 2567</a>.
12933+
</span>
12934+
Device-related error reporting via AudioContext
12935+
<div class="amendment-buttons"></div>
12936+
<ins>
12937+
12938+
<h3 id="error-handling-on-a-running-audio-context">
12939+
Handling an error from System Audio Resources on the {{AudioContext}}</h3>
12940+
12941+
The {{AudioContext}} |audioContext| performs the following steps on <a>rendering thread</a> in the
12942+
event of an udio system resource error.
12943+
12944+
1. If the |audioContext|'s {{[[rendering thread state]]}} is <code>running</code>:
12945+
12946+
1. Attempt to <a>release system resources</a>.
12947+
12948+
1. Set the |audioContext|'s {{[[rendering thread state]]}} to <code>suspended</code>.
12949+
12950+
1. [=Queue a media element task=] to execute the following steps:
12951+
12952+
1. [=Fire an event=] using {{ErrorEvent}} at the |audioContext|'s {{AudioContext/error}}.
12953+
12954+
1. Set the |audioContext|'s {{[[suspended by user]]}} to <code>false</code>.
12955+
12956+
1. Set the |audioContext|'s {{[[control thread state]]}} to <code>suspended</code>.
12957+
12958+
1. Set the |audioContext|'s {{BaseAudioContext/state}} attribute to
12959+
"{{AudioContextState/suspended}}".
12960+
12961+
1. [=Fire an event=] at the |audioContext|'s {{BaseAudioContext/statechange}}.
12962+
12963+
1. Abort these steps.
12964+
12965+
1. If the |audioContext|'s {{[[rendering thread state]]}} is <code>suspended</code>:
12966+
12967+
1. [=Queue a media element task=]to execute the following steps:
12968+
12969+
1. [=Fire an event=] using {{ErrorEvent}} at the |audioContext|'s {{AudioContext/error}}.
12970+
12971+
Note: An example of system audio resource errors would be when an external or wireless audio device
12972+
becoming disconnected during the active rendering of the {{AudioContext}}.
12973+
12974+
</ins>
12975+
</div>
12976+
1286712977
<h3 id="unloading-a-document">Unloading a document</h3>
1286812978
Additional <a href=
1286912979
"https://html.spec.whatwg.org/#unloading-document-cleanup-steps">unloading

0 commit comments

Comments
 (0)