Skip to content

OfflineAudioContext Incremental Rendering #2675

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

Merged
hoch merged 15 commits into from
Aug 6, 2026
Merged

OfflineAudioContext Incremental Rendering #2675

Changes from 3 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
28937e1
Initial draft
gabrielsanbrito Jun 5, 2026
d483465
Attempt to fix compile error
gabrielsanbrito Jun 5, 2026
c56de3b
Merge branch 'WebAudio:main' into offlineaudiocontext-progressive-ren…
gabrielsanbrito Jun 11, 2026
9e32a45
Merge branch 'WebAudio:main' into offlineaudiocontext-progressive-ren…
gabrielsanbrito Jun 18, 2026
991aa95
Addressing some feedback
gabrielsanbrito Jun 18, 2026
99cd099
Wrap text at column 80
gabrielsanbrito Jun 18, 2026
e82ea07
checkpoint
gabrielsanbrito Jul 31, 2026
3d5cab6
Incorporating WG consensus
gabrielsanbrito Jul 31, 2026
980bcd0
formatting
gabrielsanbrito Jul 31, 2026
bd3b4f0
Fixing compile errors
gabrielsanbrito Jul 31, 2026
857f48a
Speculative pr preview fix
gabrielsanbrito Jul 31, 2026
4db4f4d
Merge branch 'WebAudio:main' into offlineaudiocontext-progressive-ren…
gabrielsanbrito Aug 6, 2026
7c8e511
Revert "Speculative pr preview fix"
gabrielsanbrito Aug 6, 2026
e8787d2
check length
gabrielsanbrito Aug 6, 2026
257a31c
Undo pr-preview.json modification
gabrielsanbrito Aug 6, 2026
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
108 changes: 90 additions & 18 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2500,9 +2500,10 @@ returned promise with the rendered result as an
interface OfflineAudioContext : BaseAudioContext {
constructor(OfflineAudioContextOptions contextOptions);
constructor(unsigned long numberOfChannels, unsigned long length, float sampleRate);
Comment thread
hoch marked this conversation as resolved.
Promise<AudioBuffer> startRendering();
Promise<AudioBuffer> startRendering(unsigned long chunkSize);
Comment thread
gabrielsanbrito marked this conversation as resolved.
Outdated
Promise<undefined> resume();
Promise<undefined> suspend(double suspendTime);
Promise<undefined> close();
readonly attribute unsigned long length;
attribute EventHandler oncomplete;
};
Expand Down Expand Up @@ -2596,7 +2597,7 @@ Constructors</h4>

<pre class=argumentdef for="OfflineAudioContext/constructor(numberOfChannels, length, sampleRate)">
numberOfChannels: Determines how many channels the buffer will have. See {{BaseAudioContext/createBuffer()}} for the supported number of channels.
length: Determines the size of the buffer in sample-frames.
length: Determines the total size of the audio render in sample-frames.
sampleRate: Describes the sample-rate of the [=linear PCM=] audio data in the buffer in sample-frames per second. See [[#sample-rates]] for the required supported range.
</pre>
</dl>
Expand All @@ -2607,9 +2608,11 @@ Attributes</h4>
<dl dfn-type=attribute dfn-for="OfflineAudioContext">
: <dfn>length</dfn>
::
The size of the buffer in sample-frames. This is the same as the
The total size of the audio render in sample-frames. This is the same as the
value of the <code>length</code> parameter for the constructor.

For undefined-length rendering, this attribute SHOULD be set to positive infinity.

@hoch hoch Jun 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

IMO - since we have an explicit close() in this change, rendering indefinitely can be done by calling startRendering(chunkSize) repeatedly.

Probably this is aligned with what @karlt proposed?

@gabrielsanbrito gabrielsanbrito Jun 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I am not sure if understand this comment :/ Would you mind clarifying?

When I wrote this, I intended to have length be Infinity (after the last update it should be null) because an undefined render session has no defined length.

Do you mean that we shouldn't set length to null in the undefined length scenario and this should be tracked via an internal slot? For example, we need this info when determining the size of the returned AudioBuffer. The OfflineAudioContext needs to know whether we are in an undefined-length render or not:

<li> Otherwise, if {{OfflineAudioContext/length}} is
<code>null</code>, set <var>bufferLength</var> to the
<a>render quantum size</a>.

@karlt karlt Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Confirming that I was proposing that indefinite repeated rendering be available even when an unsigned long value for the length member is explicitly provided.

Even an optional member needs a (default) value, for which null seems a reasonable choice to correspond to "unspecified", but we need not necessarily require a specific or explicit value for indefinite repeated rendering.

@gabrielsanbrito gabrielsanbrito Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Quoting @karlt message from here:

I see the the default length of one rendering chunk (if not specified as a startRendering() parameter) as being consistent with the legacy length member.
IIUC @gabrielsanbrito sees the limit on the sum of the lengths of rendering chunks as being more consistent.
Perhaps this choice is less important if the length member can be optional.

I would prefer that startRendering(chunkSize) have control over how much is rendered, as I would see a limit from a limiting OfflineAudioContextOptions member as action at a distance.

I want to point out that, if, moving forward, the only way to close an OfflineAudioContext is via calling close(), this is potentially breaking. Currently, after the render is finished, the OfflineAudioContext goes to the "closed" state and fires a "statechange" event - i.e. after rendering length sample-frames. This means that pages that expect this state change may not work properly since we won't automatically close the OfflineAudioContext. This would be prevented by my proposal.

On a side note: I couldn't find this behavior in the spec (moving OfflineAudioContext to the "closed" state after the rendering is done), but this is what I noticed happening in both Chromium and Gecko.

Other concern is that, by allowing contexts to be solely manually closed, web pages could end up leaking resources - especially older ones unaware of close(). I recognize that this could be a minor concern since most WebAudio usage on the web is done through libraries and pages don't depend directly on WebAudio.

I am fine with adopting @karlt suggestions, although I think my concerns are valid. If we think that the breaking risk is small and that the performance implications are not that impactful, I feel like this is basically a matter of editorial preference. Both proposals should work for incremental and one-shot rendering scenarios. @hoch @padenot what is your opinion?

@karlt karlt Jul 23, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Ah, thank you for pointing that out. I had looked only at the spec and hadn't noticed that browsers were transitioning to "closed".
Even webkit is doing similarly.
Treating non-null length as a total limit allows maintaining that behavior.
I understand the consensus is to stay with the length as limit approach.


: <dfn>oncomplete</dfn>
::
The event type of this event handler is <dfn event>complete</dfn>. The event
Expand All @@ -2621,7 +2624,7 @@ Attributes</h4>
Methods</h4>

<dl dfn-type=method dfn-for="OfflineAudioContext">
: <dfn>startRendering()</dfn>
: <dfn>startRendering(chunkSize)</dfn>
::
Given the current connections and scheduled changes, starts
rendering audio.
Expand All @@ -2640,21 +2643,29 @@ Methods</h4>
<ol>
<li>If [=this=]'s [=relevant global object=]'s [=associated Document=] is not [=fully active=] then return [=a promise rejected with=] "{{InvalidStateError}}" {{DOMException}}.

<li>If the {{[[rendering started]]}} slot on the
{{OfflineAudioContext}} is <em>true</em>, return a rejected
promise with {{InvalidStateError}}, and abort these
steps.

<li>Set the {{[[rendering started]]}} slot of the
{{OfflineAudioContext}} to <em>true</em>.

<li>Let <var>promise</var> be a new promise.

<lI>Let <var>bufferLength</var> be a number initialized to the value of {{OfflineAudioContext/length}}.

<ol>
<li> If {{OfflineAudioContext/startRendering(chunkSize)/chunkSize}} is provided:
<ol>
<li> Let <var>renderedFrames</var> be the number of sample-frames already rendered by the {{OfflineAudioContext}}.

@mjwilson-google mjwilson-google Jun 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We may want renderedFrames to be an internal slot; then we can also specify when and how it is updated.

<li> If <var>renderedFrames</var> + {{OfflineAudioContext/startRendering(chunkSize)/chunkSize}} <= {{OfflineAudioContext/length}}, set <var>bufferLength</var> to {{OfflineAudioContext/startRendering(chunkSize)/chunkSize}}.

@hoch hoch Jun 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

nit: Let's explain this logic in descriptive prose rather than using abbreviated math.

@gabrielsanbrito gabrielsanbrito Jun 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks! Does it look good now? I was not sure if it was needed to make changes to the addition/subtraction.

<li> Otherwise, set <var>bufferLength</var> to {{OfflineAudioContext/length}} - <var>renderedFrames</var>.
</ol>
<li> Otherwise, if {{OfflineAudioContext/length}} is positive infinity, set <var>bufferLength</var> to the <a>render quantum size</a>.
</ol>

<li>Create a new {{AudioBuffer}}, with a number of
channels, length and sample rate equal respectively to the
<code>numberOfChannels</code>, <code>length</code> and
channels and sample rate equal respectively to the
<code>numberOfChannels</code> and
<code>sampleRate</code> values passed to this instance's
constructor in the <code>contextOptions</code> parameter.
constructor in the <code>contextOptions</code> parameter;
and length equal to <var>bufferLength</var>.
Assign this buffer to an internal slot
<dfn attribute for="OfflineAudioContext">[[rendered buffer]]</dfn> in the {{OfflineAudioContext}}.

Expand All @@ -2677,9 +2688,12 @@ Methods</h4>
occasion.

<ol>
<li>Let <var>nFrames</var> be a number initialized to the value
Comment thread
gabrielsanbrito marked this conversation as resolved.
Outdated
of the length of {{[[rendered buffer]]}}.

<li>Given the current connections and scheduled changes, start
rendering <code>length</code> sample-frames of audio into
{{[[rendered buffer]]}}
rendering <var>nFrames</var> sample-frames of audio into
{{[[rendered buffer]]}}.

<li>For every <a>render quantum</a>, check and
{{OfflineAudioContext/suspend()|suspend}}
Expand All @@ -2696,7 +2710,8 @@ Methods</h4>
<li>Resolve the <var ignore>promise</var> created by {{startRendering()}}
with {{[[rendered buffer]]}}.

<li>[=Queue a media element task=] to [=fire an event=] named
<li>If {{OfflineAudioContext/length}} is not positive infinity,
[=Queue a media element task=] to [=fire an event=] named
{{OfflineAudioContext/complete}} at the {{OfflineAudioContext}} using
{{OfflineAudioCompletionEvent}} whose `renderedBuffer` property is set to
{{[[rendered buffer]]}}.
Expand All @@ -2706,9 +2721,9 @@ Methods</h4>
</ol>
</div>

<div>
<em>No parameters.</em>
</div>
<pre class=argumentdef for="OfflineAudioContext/startRendering()">
chunkSize: The size of the desired {{AudioBuffer}}.
Comment thread
gabrielsanbrito marked this conversation as resolved.
Outdated
</pre>
<div>
<em>Return type:</em> {{Promise}}&lt;{{AudioBuffer}}&gt;
</div>
Expand Down Expand Up @@ -2803,6 +2818,63 @@ Methods</h4>
<div>
<em>Return type:</em> {{Promise}}&lt;{{undefined}}&gt;
</div>

: <dfn>close()</dfn>
::
Closes the {{AudioContext}}. This will not automatically release
Comment thread
gabrielsanbrito marked this conversation as resolved.
Outdated
all {{AudioContext}}-created objects, but will suspend the
progression of the {{AudioContext}}'s
{{BaseAudioContext/currentTime}}, and stop
processing audio data.

<div algorithm="OfflineAudioContext.close()">
<span class="synchronous">When close is called, execute these steps:</span>

1. If [=this=]'s [=relevant global object=]'s [=associated Document=] is not [=fully active=] then return [=a promise rejected with=] "{{InvalidStateError}}" {{DOMException}}.

1. Let <var>promise</var> be a new Promise.

1. If the {{[[control thread state]]}} flag on the
{{OfflineAudioContext}} is <code>closed</code> reject the promise
with {{InvalidStateError}}, abort these steps,
returning <var>promise</var>.

1. Set the {{[[control thread state]]}} flag on the {{OfflineAudioContext}} to
<code>closed</code>.

1. <a>Queue a control message</a> to close the {{OfflineAudioContext}}.

1. Return <em>promise</em>.
</div>

<div algorithm="run a control message to close an OfflineAudioContext">
Running a <a>control message</a> to close an
{{OfflineAudioContext}} means running these steps on the
<a>rendering thread</a>:

1. Set the {{[[rendering thread state]]}} to <code>suspended</code>.
<div class="note">
This will stop rendering.
</div>

1. If this <a>control message</a> is being run in a reaction to the
document being unloaded, abort this algorithm.
<div class="note">
There is no need to notify the control thread in this case.
</div>

1. <a href="https://html.spec.whatwg.org/multipage/media.html#queue-a-media-element-task">
queue a media element task</a> to execute the following steps:

1. Resolve <em>promise</em>.
1. If the {{BaseAudioContext/state}} attribute of the {{OfflineAudioContext}} is not already "{{AudioContextState/closed}}":
1. Set the {{BaseAudioContext/state}} attribute of the {{OfflineAudioContext}} to "{{AudioContextState/closed}}".

1. <a href="https://html.spec.whatwg.org/multipage/media.html#queue-a-media-element-task">
queue a media element task</a> to <a spec="dom" lt="fire an event">fire
an event</a> named {{BaseAudioContext/statechange}} at the {{OfflineAudioContext}}.
</div>

</dl>

<h4 dictionary id="OfflineAudioContextOptions">
Expand Down
Loading