OfflineAudioContext Incremental Rendering

[gabrielsanbrito]

This PR proposes changes to the Web Audio spec to enable rendering audio from OfflineAudioContexts in chunks.

Github issue: #2445
Feature explainer: https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/OfflineAudioContext/explainer.md

---

Preview | Diff

[gabrielsanbrito]

@hoch @padenot @mjwilson-google, this is the first draft for OfflineAudioContext incremental rendering. PTAL when you have some time.

While writing this, we had some open questions that might be better to discuss here:

• In this draft I am proposing using Infinity to denote the undefined-length render scenario. However, OfflineAudioContextOptions.length is currently an unsigned long, which cannot be Infinity. What would be preferrable?
  • Swap all Infinity usage for null; or
  • Convert OfflineAudioContextOptions.length to an union type like (long | float) that only accept the Infinity value for float.
• When OfflineAudioContextOptions.length is Infinity and chunksSize is not provided to startRendering(), chunkSize defaults to the render quantum size. But the render quantum size is very small. Maybe, should we consider a more optimal default?
• Should OfflineAudioContextOptions.length be a multiple of chunkSize? I am assuming it doesn't need to.

(unfortunately, there is no preview available, but I think there might be something actually broken in the repo's CI pipeline)

[gabrielsanbrito]

Audio WG meeting (06/11/2026) discussion:

1. Using null is less controversial given that the length property is a long
2. The render quantum size can be configured when the OfflineAudioContext is being constructed via the renderSizeHint parameter.
3. It's not trivial to enforce since chunkSize can change with every call. At the end of the rendering, if the chunkSize is larger than the number of remaining samples, the OfflineAudioContext just returns a smaller AudioBuffer.

[mjwilson-google]

I added some comments. Also, I think I fixed the Git workflow issue if you rebase the change on the latest commit.

[mjwilson-google]

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

[mjwilson-google]

It looks like the git checks are now passing but the PR preview still isn't working; sorry. I'm not sure why.

[hoch]

Generally looks good, but I do have some suggestions. Please take a look at my comments.

Also it would be great if you can wrap the body text at column 80.

[hoch]

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]

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]

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]

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]

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.

[hoch]

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

[gabrielsanbrito]

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

[hoch]

I'd like to have input from @karlt and @padenot on this.

[karlt]

Thank you for putting this together and for the opportunity to comment.

[karlt]

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.

[padenot]

Looks good!

[hoch]

Thanks for this contribution, @gabrielsanbrito!

LGTM